StarTeam 2008 Best Practices

StarTeam Best Practices
Getting the most from StarTeam
Randy Guck Chief Scientist, StarTeam Borland Software May, 2008
Table of Contents
1. Introduction ..................................................................................................................................................5 1.1. Welcome to StarTeam! ..........................................................................................................................5 1.2. StarTeam Has Grown Up! .....................................................................................................................5 1.3. Whats New? .........................................................................................................................................5 1.4. Overview ...............................................................................................................................................7 2. Introduction to ALM ....................................................................................................................................8 2.1. What is Version Control? ......................................................................................................................8 2.1.1. Centralized Repository ...................................................................................................................8 2.1.2. Versioning ......................................................................................................................................9 2.1.3. Focus on Text Files.........................................................................................................................9 2.1.4. VCS Operations ..............................................................................................................................9 2.1.5. Containers .....................................................................................................................................10 2.1.6. Security .........................................................................................................................................10 2.2. What is Software Configuration Management? ..................................................................................10 2.2.1. Introducing the Artifact ................................................................................................................11 2.2.2. Branching......................................................................................................................................11 2.2.3. Merging ........................................................................................................................................12 2.2.4. Sharing and Cheap Copies ...........................................................................................................13 2.2.5. Change Tracking...........................................................................................................................13 2.2.6. Development Streams ...................................................................................................................14 2.2.7. Change Rules ................................................................................................................................14 2.3. What is Application Lifecycle Management? .....................................................................................14 2.3.1. Collaboration ................................................................................................................................15 2.3.2. Process Improvement ...................................................................................................................15 2.3.3. Traceability ...................................................................................................................................16 2.3.4. Orchestrating Distributed Teams ..................................................................................................16 3. StarTeam Basics .........................................................................................................................................18 3.1. The Big Picture ....................................................................................................................................18 3.2. Standard Architecture Overview .........................................................................................................19 3.3. StarTeamMPX Components................................................................................................................20 3.4. Core Concepts .....................................................................................................................................23 3.4.1. Containers: Configurations, Projects, and Views .........................................................................23 3.4.2. Artifacts ........................................................................................................................................25 3.4.3. Artifact Versioning, Branching, and Merging ..............................................................................26 3.4.4. Items and Sharing .........................................................................................................................29 3.4.5. Links and Process Items ...............................................................................................................32 3.4.6. Labels............................................................................................................................................33 3.4.7. Promotion States ...........................................................................................................................35 3.4.8. Miscellaneous Concepts ...............................................................................................................36 4. Guidelines for Deploying StarTeam ...........................................................................................................38 4.1. Why Your Mileage will Vary ..............................................................................................................38 4.2. What is a Large Configuration? .......................................................................................................39 Borland Software Page 2 of 90
StarTeam Best Practices 4.3. What Happens When a Configuration Gets Too Large? .................................................................39 4.4. Deploying Multiple Small Configurations on a Single Machine ........................................................40 4.5. Deploying Medium Configurations.....................................................................................................42 4.6. Deploying Large Configurations .........................................................................................................43 4.7. Clustering for High Availability..........................................................................................................45 4.8. Supporting Distributed Teams .............................................................................................................46 5. Best Practices for Configuring StarTeam ...................................................................................................48 5.1. Server Configuration: How Many Do You Need? ..............................................................................48 5.1.1. Consider Business Unit Divisions ................................................................................................49 5.1.2. Leverage StarTeams Support for Distributed Teams ..................................................................49 5.1.3. Dont Partition for Internal/External Access ................................................................................49 5.1.4. Plan for Growth ............................................................................................................................50 5.1.5. Splitting-up Large Configurations ................................................................................................50 5.2. Project Configuration: Defining a Projects Scope .............................................................................51 5.2.1. Keep Projects Autonomous ..........................................................................................................51 Example 1: A Simple Client/Server Application ...............................................................................52 Example 2: An Independent Client Module .......................................................................................53 Example 3: A Complex Application Suite .........................................................................................53 5.2.2. Handle Cross-Project File Dependencies .....................................................................................53 5.2.3. Support Cross-Project Activities ..................................................................................................54 5.3. View Configuration: Understanding View Types and Roles ..............................................................55 5.3.1. View Types ...................................................................................................................................55 5.3.2. View Roles ...................................................................................................................................58 Main View: Home Base for Artifacts .................................................................................................59 Activity Views: Isolated Team Work Areas ......................................................................................59 Release View: For Post-Release Maintenance Work .........................................................................60 Sandbox View: For Small Teams or Individuals ...............................................................................61 Build View: Read-Only Windows for Build Scripts ..........................................................................61 5.3.3. View Dos and Donts ..................................................................................................................62 6. Best Practices for Common Processes .......................................................................................................63 6.1. Change Management within a View ...................................................................................................63 6.1.1. Scenario #1: Working in a Small Team........................................................................................64 6.1.2. Scenario #2: Preventing Merge Conflicts .....................................................................................65 6.1.3. Scenario #3: Using Process Items ................................................................................................66 6.1.4. Effective Use of Labels ................................................................................................................67 Scenario #1: Daily Builds ...................................................................................................................67 Scenario #2: Change Builds ............................................................................................................68 6.1.5. Miscellaneous Tips .......................................................................................................................69 6.2. Change Management across Views .....................................................................................................71 6.2.1. Overview of VCM ........................................................................................................................72 6.2.2. When to use each VCM Merge Type ...........................................................................................75 Rebase Merges....................................................................................................................................75 Promote Merges..................................................................................................................................75 Replicate Merges ................................................................................................................................76 Borland Software Page 3 of 90
StarTeam Best Practices 6.2.3. Using VCM with a Simple Project ...............................................................................................77 6.2.4. Using VCM with Activity and Sandbox Views ...........................................................................78 6.2.5. Using VCM in High Concurrency Projects ..................................................................................79 6.2.6. VCM and Process Items ...............................................................................................................80 Process Items Should Be Single-Purpose ...........................................................................................80 Where Should Process Items Be Created? .........................................................................................81 Simplified Work Status Reporting .....................................................................................................81 6.3. Administrative Processes ....................................................................................................................82 6.3.1. Performing Online Backups .........................................................................................................82 6.3.2. Managing Security........................................................................................................................82 6.3.3. Monitoring Server Performance ...................................................................................................83 6.3.4. Tuning Server Performance ..........................................................................................................84 6.3.5. Maintaining Configuration Health................................................................................................85 6.3.6. Maintaining a Test Server.............................................................................................................86 7. References ..................................................................................................................................................87 8. Glossary ......................................................................................................................................................88
Borland Software
Page 4 of 90
1. Introduction
1.1. Welcome to StarTeam! Whether youre a StarTeam newcomer or an experienced veteran, welcome! The goal of this document is to bring you tips, techniques, and practices that help you use StarTeam successfully in your environment. The information presented here supplements the standard StarTeam guides and manuals, providing how to advice not found elsewhere. These best practices are cultivated from years of experience helping customers get the most from StarTeam. We hope this information helps your organization as well. 1.2. StarTeam Has Grown Up! Back in 2006, StarTeam celebrated its 10-year anniversary. As most of us that have worked on large software systems know, this is no small feat. Most sophisticated applications succumb to software entropy or simply arent valuable enough to survive even 10 years. We like to think that StarTeam reached its first decennial birthday because weve listened to you, our customers, and weve worked hard to meet your needs. Were not surprised that Joel Spolsky says, Good software takes ten years get used to it. [Spolsky] StarTeam began as a software configuration management (SCM) tool for small teams on Windows a niche back in 1996. StarTeam was the first SCM product to combine traditional file version control with defect tracking in an integrated, graphical product. Over the years, StarTeam has expanded on all fronts: features, platforms, performance, and scalability. StarTeam is now used by international companies, allowing thousands of globally distributed users to share a common repository. Enterprises now use StarTeam to integrate application lifecycle management (ALM) activities in truly global spanning organizations. 1.3. Whats New? Since 2006, StarTeam has seen some significant changes and improvements to some fundamental aspects of the product. The 2006 release was a watershed release for more reasons than just its coming of age. It is one of the biggest releases in recent years, introducing many important new features such as: Atomic transactions: StarTeam provides a new multi-artifact update capability that supports full ACID1 transactions. For example, you can check-in multiple files, link them to a change request, mark the change request fixed, and attach the files to new revision label, all in one atomic transaction. View compare/merge: Known as VCM, this new change management facility provides a powerful way to propagate changes within StarTeam. VCM elevates StarTeam change management to a whole new level.
ACID properties are the yardstick of database transactions: atomicity, consistency, isolation, and durability.
Borland Software
Page 5 of 90
StarTeam Best Practices Integrated visual file differencing and merging: StarTeam provides a new graphical file comparison and merging tool, tightly integrated with StarTeam clients at key touch points to greatly improve file management. Unlimited file size: Building on the highly-scalable Native-II vault introduced with StarTeam 2005, the 2006 release allows individual file revisions to be unlimited in size2. Combined with StarTeams equal proficiency at managing text and binary files, this feature opens-up whole new media types that can be managed with StarTeam. New client customization features: The StarTeam cross-platform client (CPC) provides new customization features, allowing each user to see exactly what they want. Client usability improvements: The StarTeam CPC provides numerous new features and usability improvements in managing folders, navigating to referenced items, customizing properties dialogs, and more. Expanded platform support: StarTeam components are now available on more platforms with almost no platform-specific restrictions: the StarTeam server now supports Linux and VMWare ESX; HP-UX is a supported client platform; and virtually all clients are supported on all platforms.
And since StarTeam 2006 we have made even more progress up to the latest release of StarTeam 2008. Some of the key advancements include: Improved Performance: Newly added MPX Object Caching allows for an even greater performance improvement for accessing and working with non-file items (CRs, Tasks, Requirements and Topics). In addition we improved Borland Search by providing parallel support on the indexing servers, as well as significantly improved the performance of list controls on custom forms (APEs). Improved Usability: It is now possible to compare content within the same view with the VCM (not just between different views/branches). Weve added support for non-derived views within the VCM. We also added a new type of Enhanced Process Links and Process Tasks to the way StarTeam handles process items and automatic link creation. Process Guidance & Support: Weve tried to improve the way the tool provides guidance on process automation by for example creating the ability to prevent the creation of Advanced Views (prevent floating views) and also by allowing users to select cross project process items when doing their work, thus making it easier to separate change-control projects from those where the actual software assets are being stored and managed. Platform updates for StarTeam 2008: The platform support situation is of course always evolving and the latest changes includes Microsoft Vista support (for the Cross Platform Client, SDK,
Well, technically files are limited to a maximum of 263 - 1 bytes. But, at over 9.2 x 1018 bytes (thats 9 exabytes, if you must know), we consider this virtually unlimited.
Borland Software
Page 6 of 90
StarTeam Best Practices command line, and bulk check-out utility), 64-bit Oracle DB support and SQL Server 2005 support (for both the StarTeam server and the Datamart). Some platforms were obsolete: Oracle 9 DB, SQL Server 2000, Linux RH 3 (for the CPC) and Solaris 9 (for the CPC). For a complete list of new features for StarTeam 2008, see the Whats New topic in the StarTeam Help documentation or the Administering and Using StarTeam manual. Since the release of StarTeam 2006 and up to the very latest StarTeam 2008 release, we have developed some new techniques and practices to pass along. StarTeam now provides whole new ways to accelerate software development. 1.4. Overview This document updates and supersedes the documents StarTeam Configuration Best Practices and StarTeam Performance & Scalability document, both dated December, 2003. Best practices are updated to reflect capabilities of the StarTeam 2006 release and new experience garnered from customer successes and even some mistakes since then. This document provides guidelines on how to use StarTeam in several categories: deployment, configuration, short- and long-term operation, and administration. To help you decide which sections you should read, heres a summary of whats in each one: Introduction to ALM: This section explains foundation concepts on version control, software configuration management, and application lifecycle management. If youre new to StarTeam or these concepts, this should help you understand where StarTeam fits in the software management landscape. StarTeam Basics: This section provides an overview of core StarTeam concepts: containers, artifacts, items, links, and so forth. If youre new to StarTeam, this section is a must. Guidelines to Deploying StarTeam: This section is designed to help you plan new StarTeam deployments or evolve existing ones. It covers topics such as hardware configuration alternatives, high availability concepts, and optimizing StarTeam for distributed teams. IT managers and administrators will definitely want to read this section. Best Practices for Configuring StarTeam: This section provides considerations for how you should set-up and organize the primary StarTeam containers: configurations, projects, and views. This information describes the best techniques that other customers have successfully used. Best Practices for Common Processes: This section gets to the heart of the question how should I use StarTeam? We provide our best advice on daily operational topics such as change management, security administration, and backups.
For many users, the last section will be the most important. So if you cant wait, start there. For some topics, we summarize material that is discussed in greater depth elsewhere and point to those documents for more details. In other cases, this document covers important topics in depth. Borland Software Page 7 of 90
2. Introduction to ALM
Application Lifecycle Management (ALM) is an important evolutionary step in the effort to successfully manage software development. ALM is a process in which StarTeam plays a central role. In order to understand what ALM is, this section describes what came before it and why it has become important. Although you can think of version control, software configuration management, and ALM as a capability hierarchy, the lines between them are blurred by that fact that some applications (including StarTeam) provide benefits from each of these layers. Read this section if youre new to these concepts or want to see how StarTeam draws from all of them. 2.1. What is Version Control? When the first developer accidentally wiped out some changes while saving a file, version control was born. Late that night while working under the glow of a teletype, this same user created the worlds first version control system (VCS).3 The need for version control becomes readily apparent to anyone who at some point realizes that an older version of a file is the one they want now. And, when many people work on the same set of files, other VCS requirements become quickly apparent: identification, locking, security, and so forth. At its core, the goal of version control4 is to store and maintain an accurate history of changes for a set of files. The first version control system is generally agreed to be the Source Code Control System (SCCS), developed in the early 70s. The popular Revision Control System (RCS) was later developed in the 80s. It was superseded by the open source VCS known as the Concurrent Versioning System (CVS) and other CVS-compatible or partially-compatible follow-on systems such as CVSNT and Subversion. The features most important to a VCS are summarized below.
2.1.1. Centralized Repository
The main purpose in life of a VCS is to store file revisions. To make them accessible to multiple users, file revisions are typically stored in a repository. The repository may consist of a set of OS-level files, a database, or both. Putting the repository on a centrally-accessible server has many advantages. It can be made accessible throughout the company and even externally with sufficient security controls. Each user can copy exactly the file revisions they want to their workspace. Backing-up and securing the repository is easier when it is centralized. And so forth.5
The credit for the first VCS goes to SCCS, created in 1972. Since it was developed for a mainframe, we assume a teletype was involved. For you kids, a teletype is an early computer terminal. Think typewriter with a long roll of paper. No, they dont actually glow in the dark. Now, dont ask what a typewriter is.
4
Version control is also known as revision control, so the term revision control system applies as well.
For completeness, we must point out that peer-to-peer networking introduced an alternative to the centralized repository model. In lieu of a central authority, file revisions are copied from workstation to workstation as needed (like free music). This model has been used successfully with small teams, but it introduces difficult issues in terms of scalability, control, security, backup, and so forth. We wont discuss it further here. And just for the record, we had nothing to do with that free music stuff.
Borland Software
Page 8 of 90

2.1.2. Versioning
Since a VCS may have multiple versions of a single, conceptual file such as foo.java, we need a way of distinguishing them. To do this, every new revision added to the repository is assigned a sequential version number. Depending on the VCS, the first revisions version number may be 0 or 1; each modification thereafter increments the version number. Each file is independently numbered. Figure 1 shows a zerobased version sequence.
Initial revision (file added) Update revisions (file modified)
File: foo.java 0 1 2 3 4
Version numbers
Figure 1: Version numbering
An industry convention is to refer to the most recent revision available for a file as the tip revision.
2.1.3. Focus on Text Files
Because they were born from the need to manage source code, VCSs typically focus on text files. This allows them to use deltas to leverage the line-oriented nature of text files to minimize storage space. Nontext files are typically not supported at all or not supported well. (For example, binary files may experience performance problems, size limits, or other issues.) A VCS also does not provide version control for change requests, tasks, and other non-file artifacts. As we will discuss later, we need features from SCM applications to manage non-file artifacts.
2.1.4. VCS Operations
To allow users to interact with the repository in a controlled manner, a VCS provides basic operations such as the following: Add: Add a brand new file to the repository. Since a VCS is aware of folders, you tell the VCS to add the file to the appropriate folder. Get: Fetch a specific file revision, copying it to the local workspace. A get does not lock the file; hence the VCS may mark your local file copy as read-only so youre reminded not to modify it. Check-out: This is a get with lock. That is, the VCS copies the file to your local workspace (if its not already there) and locks it in the repository, preventing others from performing a check-out. (However, other users can still get the file.) When you have the lock, the VCS typically makes your local file copy modifiable. Check-in: After a file is modified locally, this operation posts the new revision to the repository, assigning it the next version number. When you check-in, your lock is typically released at the same Page 9 of 90
Borland Software
StarTeam Best Practices time so that someone else can perform a check-out. This means that your local copy may be marked read-only again since you no longer have the lock. As you can see, locking is a key VCS capability. Acquiring a lock during check-out and releasing it at check-in avoids the possibility that two users both think they have control of the file. Otherwise, if two users both modified the same file and then checked-in their changes, the second user could wipe-out the changes made by the first user. As well see later, allowing multiple users to work on the same file at the same time is an important capability. Such parallel development requires additional features such as branching and merging. Although some VCSs support parallel development, it is typically not their strong suit. Well probe this topic more under SCM.
2.1.5. Containers
For some reason, having everyone on planet earth store their files in a single repository doesnt scale well. Consequently, VCSs allow multiple repositories, sometimes referred to as instances. Within an instance, a VCS may provide additional containers such as projects, subprojects, or views.6 These containers allow you to separate files within a repository based on application, module, business unit, or other criteria. VCSs also provides tags (or labels) that you can apply to an arbitrary set of file revisions. A tag is a snapshot that identifies files related to a specific purpose (e.g., the 2.1 release build). A VCS typically supports a client-side container called a workspace. In addition to providing a welldefined area for check-in/check-out operations, a workspace allows a VCS to compute the status of each file: which ones have been modified since they were checked-out, which ones are out-of-date, and so forth.
2.1.6. Security
Minimally, a VCS must support repository-level security, restricting the users who can access the repository. Some VCSs rely entirely on OS-provided, file-level security for all access. Some VCSs offer finer-grained access control on lower-level containers (projects, folders, and individual files). Access control specifies which users and user groups can access these containers. Correspondingly, permission control specifies what each user or group can actually do: read, add, update, delete, etc. 2.2. What is Software Configuration Management? At your company, everyone just works on one release at a time, right? And when it ships, you forget about it and move on to the next release, yes? No, we dont know anyone who works that way either. Very few companies have the luxury of worrying about only one version of an application at any given time. If youre like most companies, you have a current release in the field, a new release under development, and several older releases still being supported. If you find a bug in the current release, you may have to fix it in two older releases, but sometimes the fix isnt quite the same in each release. And tomorrow, you may need to rebuild an old field test release so you can duplicate a problem found there. Oh,
Amazingly, some VCS systems have no container other than an instance!
Borland Software
Page 10 of 90
StarTeam Best Practices and your boss has this great idea to start three new releases in parallel, each delivering functions 3, 6, and 9 months out. And surprise, youre going to need another service pack for that last release. In short, you need software configuration management (SCM). The primary purpose of SCM is to allow parallel development. The term SCM was well-chosen as it aptly describes the activities of parallel development: Software: The focus of SCM is not just source files, but all artifacts needed to develop software applications. This includes all files required to produce software resource files, build scripts, thirdparty libraries. But software development often involves artifacts that may not naturally exist as files: requirements, defects, enhancement requests, tasks, and so forth. SCM allows you to manage these artifacts well. Configuration: SCM seeks to provide precise definitions of specific artifact configurations. For example, you can create a configuration that identifies an approved set of requirements or all the files used to create a field test build, including the compilers, build scripts, and other tools. Reproducibility of specific configurations is important for traceability, auditing, and in some cases even regulatory purposes. Management: This means that the flow of changes to existing configurations and the creation of new ones are controlled and tracked. SCM allows you to define rules or workflow that control what can be changed by who.
As you can see, SCM requires the features of version control, but it adds a significant layer on top. Lets examine the key features in this layer more closely.
2.2.1. Introducing the Artifact
Weve already used the term artifact, but lets single out what it means to SCM. A typical software development lifecycle requires the development, evolution, and management of things other than source files such as requirements, models, graphics, change requests, schedules, tests, and so on. The term artifact refers to the generalization of objects that can be versioned, branched, merged, etc. Because SCM emphasizes management of all artifacts required to produce software, it must address management of more than source files. Some SCM systems accommodate non-file artifacts by serializing them into files and applying file-based version control. Other SCM systems support non-file artifact types directly, providing type-specific behavior for storage, versioning, merging and so forth. Yet another approach is to provide an SCM solution as an integration layer on top of multiple, lower-level tools such as VCS, defect tracking, and change management applications. How artifact generality is addressed varies greatly from one SCM system to another, but the goal of SCM is to manage all artifacts.
2.2.2. Branching
Branching allows an artifacts version stream to be forked. Each fork can be independently modified, receiving its own versions. Theres a big difference between copying an artifact and branching an artifact. Although copying allows each copy to be modified independently, the SCM system does not know that Borland Software Page 11 of 90
StarTeam Best Practices copied artifacts are related to each other in the repository. In contrast, with branching, the SCM system retains special knowledge about an artifacts branches. This information supports things such as intelligent revision comparison and three-way merging (discussed in the next section). An example of branching and merging is shown in Figure 2.
Main branch
0 1 2 3 4
New branch created from main branch version 1

0 1 2 3
Revision 3 on the lowest branch merged to both upper branches
New branch created from main branch revision 2
0 1 2 3 4
Figure 2: Branching and Merging
When a new artifact is added to the repository, a main branch is started and new revisions are added to it. At any time, a parallel child branch can be started. In this example, one child branch is created from main branch version 1, and another child branch is created from main branch version 2. Within a branch, the version number starts over (at zero in this example). New revisions are applied to a specific branch, incrementing the version number on that branch but not affecting other branches. Branching is needed to support parallel development on files. However, there are advantages to allowing non-file artifacts to branch as well. For example, if a defect artifact can be branched, the two branches can be used to track fixes to the same defect that exist in different releases. Not all SCM systems support branching for non-file artifacts.
2.2.3. Merging
Inevitably, a change on one branch will need to be propagated to another branch. In Figure 2, version 3 of the artifact on the lowest branch is applied to both of the parent branches. However, you cant just copy a revision from one branch to another branch this could wipe-out changes that are specific to the target branch. Instead, what you want to do is merge the changes from the source to target branch.7 More specifically, SCM systems store synchronization information that allows three-way merging. The three parts of a merge operation are (1) the source revision containing changes to be propagated, (2) the target revision that will be modified, and (3) the last source revision common to the source and target branches, known as the common ancestor.
Note, however, that overwriting the target artifact with the source revision instead of merging it is sometimes the desired effect, for example with binary files.
Borland Software
Page 12 of 90
StarTeam Best Practices For files, merging is typically done by passing these three file revisions to a three-way file merge tool. The tool compares both the source revision and target revision to the common ancestor revision and determines two important things: (1) what changes appear in the source revision only that should be propagated to the target revision, and (2) what changes appear in the target that may conflict with changes in the source revision. In many cases, merging detects no conflicts, so the merge tool automatically propagates the source changes to the target revision. When conflicts are detected (and sometimes even when none are), the merge tool typically displays the differences to a user who can review the differences, resolve conflicts, and approve the final result. The merge tool then creates a result file reflecting the target file updated with changes. The SCM system adds the result file to the target revisions branch, creating a new revision. In Figure 2, revision 3 on the lower child branch was merged to both of the upper branches. When it was merged to the main branch revision 3, it created main branch revision 4, which contains the merge results. (The arrow points to the revision that was created as a result of the merge.) For this merge, the common ancestor between the two branches is main branch revision 2: it is the most recent revision that both branches had in common. When the lower child revision 3 is merged with upper child branch revision 2, upper child branch revision 3 was created. For this merge, the main branch revision 1 is the common ancestor. For files, there is more to merge than contents. In an SCM system, files have other properties such as name and description. Merging a file requires merging these properties as well, for example to propagate a name change. Non-file artifacts that branch also require merging in order to propagate changes.
2.2.4. Sharing and Cheap Copies
Over time, you will have a lot of artifacts especially files and some files will have a lot of branches. Consider the effect of containers: if you have a lot of teams, software components, and releases, you will need a lot of independent projects, subprojects, or other containers to support parallel development and separate maintenance. Often the same files will be needed in each of these containers. How do you get the files you need to each of these containers? Forcing every file to branch in order to get a unique branch in every possible container could be a lot of branching, which is expensive. SCM systems address this problem with a technique known as cheap copies. This involves creating references to files in a new container. Similar to Unix links, this happens without actually copying the files themselves (that is, their content or their history). Unlike Unix links, however, the first time a file is modified via a new reference, it is branched. For this reason, cheap copies are also referred to as copy on write sharing. Cheap copies are an important SCM feature to support efficient branching with large projects.
2.2.5. Change Tracking
When we develop software, we tend to work in specific units of work: implement a feature, fix a bug, add a unit test, and so forth. Often a single change involves updates to multiple files. Although it is useful to see the history of individual files, sometimes we want to see why a certain file revision was created and what other files were modified for the same reason. Tags can help, but what we really want is a change container into which artifacts can be placed that are related to the same unit of work. Borland Software Page 13 of 90
StarTeam Best Practices Lots of such change containers are used by different SCM systems, going by names such as activities, change sets, change packages, jobs, and so forth. Whats common to these various facilities is that they allow use to see what was actually changed as well as the work artifacts that support the reason for the changes: requirements, defects, tasks, etc. Moreover, SCM systems typically allow the related artifacts to be placed inside the container and then applied or committed in an atomic transaction. The use of atomic transactions ensures that the entire set of changes is applied or none of them.
2.2.6. Development Streams
So far, weve talked about containers that hold sets of artifacts: projects, subprojects, folders, etc. Weve also talked about branches as parallel version streams for individual artifacts. In practice, we need to develop or maintain sets of artifacts related to a specific long-term activity: new feature development, bug fixes, a service pack release, etc. In other words, we need a container where the branch of every artifact it contains is dedicated to the corresponding activity. Whether they are for new development or maintenance, well call this intersection of containers and dedicated artifact branches a development stream. Think of a development stream as a place where we may apply a continuous stream of work-specific changes as described in the previous section. In some SCM systems, a container type is the same as a development stream. For example, a subproject may be used to separate artifacts belonging to different applications, but a subproject may also be the mechanism used to create multiple development streams for the same application. In other cases, an SCM system may provide separate mechanisms for containers and development streams8.
2.2.7. Change Rules
It is not enough to simply capture and organize artifact revisions. SCM systems typically provide a way to control which users can make changes and when. (After all, were talking about software configuration management.) Security rules provide part of the solution, but security typically does not consider an artifacts state. Consequently, some SCM systems allow you to define change rules that affect how certain changes can be made. An example rule may be that a defect can only be marked fixed by someone in the QA group. Another rule may be that files cannot be added or modified unless a task or other work item is selected as the context, allowing the SCM system to record that context along with the file changes. 2.3. What is Application Lifecycle Management? SCM is not the only process that occurs in software development. Most organizations also use a combination of requirements management, modeling, coding, build management, test management, deployment, and other processes. Although fundamental SCM concepts such as artifacts, versioning, and change management thread throughout these processes, managing the end-to-end lifecycle requires a layer above them all. Application lifecycle management (ALM) is the coordination of all activities in the software development lifecycle. Compared to SCM, whose focus is the management of specific branches, components, and
Confusingly enough, such a development stream is sometimes called a branch, not to be confused with the version branches of individual artifacts.
Borland Software
Page 14 of 90
StarTeam Best Practices artifacts, ALM broadens the management scope to entire project lifespans and finished goods: complete applications delivered for a specific business goal. ALM is a discipline aimed at improving efficiency and reducing errors. As such, it can be practiced independently from the tools used in any specific development phase. However, practicing ALM is a laborintensive process without support from the tools used in the lifecycle. The following sections describe some of the key features that an ALM solution must address.
2.3.1. Collaboration
If you had to summarize ALM in a single word, you could say that its all about collaboration. Software development management has evolved from the VCS focus of managing bits to the SCM focus of managing change to the ALM focus of managing processes. Since processes are the activities of people and tools, this means ALM facilitates the collaboration between people and tools. ALM seeks to coordinate people on the same team and those on different teams involved in different project phases. For example, ALM provides a way for QA people to not only see business requirements but to communicate with business analysts. One collaboration issue that ALM must grasp is information timeliness. As our teams get bigger, our application portfolios grow, and our processes become more sophisticated, we cannot depend solely on information pull. That is, we cannot rely on users monitoring large sets of information to discover work they need to address. Time-sensitive information must be pushed on an event or exception basis to appropriate people and tools. ALM solutions provide event-based notifications in a variety of ways such as email and publish/subscribe messaging frameworks. An important use case for ALM collaboration is progress reporting. Team leads, project managers, and executives need to see the big picture via customized reporting, analytics, and even data mining. By integrating tools, artifacts, and people, ALM gives managers the oversight they need for monitoring activities and making mid-course corrections.
2.3.2. Process Improvement
If collaboration is the short answer to what is ALM about, process improvement is the short answer to what is ALMs goal. In different organizations, process improvement may be known as process enforcement, reengineering, or enactment. Regardless, the goal of ALM is the same: improve the predictability, quality, and efficiency of software projects. Said another way, ALM strives to reduce process variance, minimize defects, and expend resources more intelligently. Sometimes process improvement is motivated by regulatory pressures (FDA, EMEA, Sarbanes-Oxley), internal evolution towards software development maturity models (COBIT, CMMI, ITIL), or a combination of these. It is important to note that ALM does not promote a specific development process. Rather, it provides a framework for which a chosen methodology can be monitored and managed. In fact, large organizations will often want to use multiple methodologies simultaneously. Which process is appropriate for a given project depends on the team size, its maturity, application size and complexity, and other factors. Whether the methodology is waterfall, RAD, agile, or a custom process, the role of ALM is to allow the methodology to be fine-tuned to reflect lessons learned. Over time, this ensures that teams follow established best practices. Borland Software Page 15 of 90
StarTeam Best Practices The role of a specific ALM solution, then, is to support the specific processes that the organization wishes to use. This has a number of implications: Automation: As much of the development lifecycle should be automated as possible. Every step that can be codified improves conformance and reduces process errors. Customization: An organization must be able to customize artifact workflows, event-based applications, and even artifact types to support the processes they use. Even end-user tools should be customizable to fit the needs of specific end-user roles. Extension points: It must be possible to add new tools to the ALM framework and integrate them with other tools.
Process improvement by managing interactions across development phases is highly dependent on the ALM factor discussed next: traceability.
2.3.3. Traceability
Traceability is an important function that ALM fulfills above phase-specific tools. It entails the linking of artifacts to represent specific relationships: requirements to design artifacts, defects to modified files, parent tasks to child tasks, test cases to requirements, etc. Traceability is important to prevent divergence of the final application from the initial requirements it lets us to follow the original target through its entire lifecycle. It is important that traceability is bi-directional. For example, a business analyst may want to know when test cases are written that verify specific requirements. Conversely, a QA engineer writing test cases must be able to review requirements in context to his or her work and know when they change. (Arguably, everyone in the lifecycle needs to correlate their work back to the appropriate requirements.) By spanning tools and development phases, traceability gives us greater schedule predictability, quality control, and process auditing.
2.3.4. Orchestrating Distributed Teams
Increasingly, we live in a world of globally distributed development (GDD). Even small- to medium-size companies find themselves with software teams in different time zones and on different continents. Whether they are internal groups, contractors, or off-shored development, distributed teams are becoming commonplace. While distributed teams yield benefits such as follow-the-sun development, they impose special collaboration problems as well: Information integrity: How do you provide distributed teams access to up-to-date requirements, source code, defect reports, test cases, and other artifacts? How do we prevent contradictions and ensure one version of the truth? Process compliance: How can you ensure that remote teams are following corporate development practices?
Borland Software
Page 16 of 90
StarTeam Best Practices Scalability: How do you scale the information infrastructure to accommodate thousands of distributed users who need to access millions of artifact revisions, potentially representing terabytes of data? High availability: Given that software development has become a mission-critical business operation, how do you keep information available to practitioners on a 24 x 7 basis? Administration: How do you backup, secure, and monitor repositories in a distributed topology?
In the pre-ALM era, wed expect to find each team independently addressing these issues on a geographicor project-specific basis. Wed probably find a hodgepodge of solutions with greatly varying degrees of attention to each issue. When we elevate our focus to ALM, we expect these issues to be addressed uniformly across the entire development organization.
Borland Software
Page 17 of 90
3. StarTeam Basics
In this section, well review StarTeam basics: its architecture, key components, and core concepts. Well map StarTeams terminology and features to the VCS, SCM, and ALM concepts described in the previous section. If youre new to StarTeam or want to brush-up on the essentials, read on. 3.1. The Big Picture If you just read section 2, you may be wondering: how would we classify StarTeam? Is it a VCS tool, an SCM application, or an ALM solution? Well, you have to read the rest of this document and well reveal the answer on the last page. Oh, youre one of those who reads the last page when the suspense is too much? All right we wont make you wait: heres how we classify StarTeam: StarTeam supports all of the features of a VCS: a centralized repository, versioning for all file types (not just text), all basic VCS operations, different container types, and fine-grained security. StarTeam is also a complete SCM application: it supports file and non-file artifact types; branching and merging; artifact sharing (cheap copies); change tracking; development streams; and change rules. StarTeam supports enterprise ALM foundation features in the following ways: Collaboration: A topic artifact supports threaded discussions, and event-driven notifications are provided via email and publish/subscribe messaging. Read-only audit artifacts are automatically generated to provide a detailed log of all data modifications. Customization: StarTeam provides customizable workflow, forms, and artifact properties. An SDK supports custom event-driven applications and the integration of new tools. Bundled graphical clients provide per-user customization features. Traceability: A flexible link facility allows arbitrary artifacts to be related within the repository. Distributed teams: StarTeam uses a unique architecture that allows thousands of users worldwide to access a single instance without replication. Borland Search is a search engine that provides secure searching across multiple StarTeam (and CaliberRM) repositories. StarTeam Datamart is a data mining application that provides multi-repository analytics and custom reporting. StarTeam is integrated with other Borland ALM products (e.g., CaliberRM, Silk, Tempo, and Together), popular IDEs (e.g., JBuilder, Eclipse, Delphi, Visual Studio), and other repository-based products (e.g., HP Quality Center). In short, we cant say that StarTeam is an all-in-one ALM solution, but it is far more than a VCS or even an SCM system. Companies use StarTeam because they are building ALM, and StarTeam provides a strong foundation.
Borland Software
Page 18 of 90
StarTeam Best Practices 3.2. Standard Architecture Overview The core components of StarTeam architecture are depicted in Figure 3.
StarTeam Clients
CrossStarTeam Platform SDK Client Database Server StarTeam AdminisSDK trator LAN, WAN, VPN, etc.
command API
Network
StarTeam Server
Vault StarTeam Server process

Hive 1
Files
Command StarTeam Line SDK Interface
TCP/IP
Hive 2
Files
Custom StarTeam ApplicaSDK tion
As you can see, StarTeam employs a client/server architecture. The Cross-Platform Client (CPC), Server Administrator, and Command Line Interface are example bundled StarTeam clients. StarTeam clients use the freely available StarTeam SDK, so you can write custom applications that have access to the same features as the bundled clients. The SDK is fully featured in Java, .Net, and COM flavors, allowing you to write custom applications for any environment. A single StarTeam client can have multiple sessions to any number of StarTeam servers. All StarTeam clients connect to a StarTeam Server process using TCP/IP, so virtually any kind of network can be used: LAN, WAN, VPN, or the public internet. StarTeam uses a proprietary protocol called the command API, which supports compression and multiple levels of encryption. The command API has been optimized to support high performance, automatic reconnect, delta check-out for slow connections, and other important features. A single deployment instance of StarTeam is known as a server configuration, usually shortened to just configuration. The persistent data of a configuration consists of a database and a vault and is managed by a single StarTeam Server process. The database holds all metadata and non-file artifacts, whereas file contents are stored in the vault. The database can be Microsoft Desktop Engine (MSDE), full SQL Server, or Oracle, and it can reside on the same machine as the StarTeam Server process or a separate machine. Borland Software Page 19 of 90
Figure 3: Overview of the StarTeam Architecture
StarTeam Best Practices In its SCM capacity, StarTeams vault is a critical component that affects performance and scalability. In contrast to the traditional delta storage technique, StarTeams vault uses an innovative (patent pending!) architecture designed for scalability, performance, high availability, and dynamic expandability. Today, customers are storing up to a terabyte of data in a single StarTeam vault, but it was designed to store content up to a petabyte and beyond. Within the vault, files are stored in containers known as hives. A hive is a folder tree containing archive and cache files on a single disk volume. Hives can be dynamically added on existing or new disk volumes, thereby allowing virtually unlimited capacity. StarTeam stores each file revision in a separate archive file in a manner that minimizes space usage as well as duplicate content. Amazingly, StarTeams vault uses less space than delta-based storage!9 The StarTeam database and vault can be backed-up dynamically, while the server is in use. This supports 24 x 7 operations that want to minimize down time. Other high availability features and techniques are discussed later. 3.3. StarTeamMPX Components The standard architecture described in the previous section represents the minimal components present in a StarTeam instance: a StarTeam Server process managing a vault and a database and one or more StarTeam clients. With just these components, all basic StarTeam functionality is available. Like all client/server architectures, as the number of clients grows, the server could potentially become a bottleneck. In fact, the scalability of many client/server systems is entirely limited by this bottleneck. Other client/server systems address scalability by deploying multiple instances and replicating information between them to attain synchronization. StarTeamMPX (or simply MPX) is a unique solution to client/server scalability. MPX is a publish/subscribe messaging framework that pushes update events that contain metadata and data to clients. It is optional because it is not required for basic StarTeam functionality. However, when MPX is activated, it improves StarTeam server scalability and improves StarTeam client responsiveness. Basic MPX requires the addition of a single extra component, known as the Message Broker. The Message Brokers role is illustrated in Figure 4.
In certain cases where it is more economical to send file deltas to clients instead of full versions, StarTeam generates and caches delta files. However, in most cases sending full versions is more economical.
Borland Software
Page 20 of 90
Client
Client
command API
Database StarTeam Server process Vault

event API
Client
Client
update events
MPX Message Broker
Figure 4: Role of the MPX Message Broker.
The Message Broker is a messaging process that uses an event API to receive updates from the StarTeam Server process. The Message Broker broadcasts encrypted messages containing updated artifacts. StarTeam clients subscribe to subjects and receive only messages relevant to them. By receiving updates as soon as they occur, StarTeam clients do not need to poll for updates or refresh information they have cached, significantly reducing the demand-per-client on the StarTeam server. This improves server scalability, but it also improves client responsiveness since updates are received within seconds after they occur. Messages broadcast by a Message Broker benefit clients with active sessions. However, for files MPX offers an optional Cache Agent process that manages its own persistent cache. Cache Agents can be deployed at geographic locations, allowing clients to fetch file contents from the nearest Cache Agent, preventing the need to fetch this content across a longer (and potentially slower) network connection. MPX Cache Agents are illustrated in Figure 5.
Borland Software
Page 21 of 90

Remote site Server site
Client
Database Client
command API
StarTeam Server process Vault
Client
broker-tobroker forwarding file checkouts
Client
update events
Root Message Broker

update events
Root Cache Agent

file checkouts
Remote Cache Agent
Remote Message Broker
to local clients
Figure 5: MPX Cache Agents
In this example, a Root Cache Agent is deployed network-near to the StarTeam Server process. A Root Cache Agent directly accesses the StarTeam vault, providing local clients with an alternate path to the vault for checking-out files. This reduces demand on the StarTeam Server, enhancing its scalability. This example also shows a Remote Message Broker and a Remote Cache Agent deployed at a remote site. Utilizing broker-to-broker forwarding, each update event is forwarded once to the Remote Message Broker, which then broadcasts it to local clients. Files are streamed to the Remote Cache Agent, which stores them in an encrypted private cache. StarTeam clients network-near to the Remote Cache Agent can check-out files at any time, leveraging the local high-speed network instead of pulling content across the WAN. This further reduces demand from the StarTeam Server while improving remote client responsiveness. Though not shown in this example, MPX offers many other benefits for distributed organizations: An optional companion to the Message Broker is the Multicast Service, which broadcasts messages to local clients using IP multicast. This broadcast protocol further reduces network traffic in large client communities.
Borland Software
Page 22 of 90
StarTeam Best Practices Any number of Message Brokers can be chained together (typically in a hub-and-spoke configuration) to form a messaging cloud that scales to any size organization.10 Any number of Cache Agents can be distributed globally. Clients can be configured to automatically locate and use the network-nearest Cache Agent, or they can choose a specific Cache Agent. Cache Agents use push caching in which content is broadcast and stored by Cache Agents as soon as it is created. This makes caches more effective than traditional pull through caching, in which every initial request results in a cache miss. Cache Agents use advanced synchronization techniques that improve their effectiveness such as pre-charging, tiering, request forwarding, and automatic catch-up.
In summary, MPX provides a unique solution for distributed teams. It leverages the benefits of a centralized server lower total cost of ownership, better security, and simplified administration while solving the traditional performance and scalability issues of client/server architectures. Later, well discuss options for deploying core StarTeam and MPX components. 3.4. Core Concepts In this section, well explore core StarTeam concepts such as containers, artifacts versus items, links, labels, and so forth.
3.4.1. Containers: Configurations, Projects, and Views
Containers are the basic building blocks for organizing information. The three basic containers that StarTeam provides are illustrated in Figure 6.
10
If youre an existing StarTeam user, you may recall that there used to be a 1,000 connection per Message Broker limit, and a ten Message Broker per cloud limit. With the StarTeam 2006 release, these limits have been lifted. Message Broker limits can now be configured to arbitrary values based on available resources such as file handles.
Borland Software
Page 23 of 90
Server Configuration Prod1

Project BedRock BedRock (main view) Project AppSuite AppSuite (main view) Sources (child view) BedRock 1.0 (child view) Pegasus (child view) DocWork (child view) Public Docs (grandchild view) Bobs Sandbox (grandchild view) Team1 Sandbox (grandchild view) Jeans Sandbox (grandchild view)
BedRock SP1.0 (grandchild view)
BR SP1 HotFixes (great-grandchild view)
Figure 6: StarTeam Containers
As described in section 3.2, a server configuration is a deployment instance of StarTeam. All files, change requests, and other artifacts that can be interrelated and managed as a whole reside in the same configuration. The configuration in Figure 6 is named Prod1. Suggestions for deciding when to create a new server configuration are discussed in section 5.1. Within a configuration, artifacts are organized into projects. Before a 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. The configuration in Figure 6 has two projects: BedRock, perhaps for foundation components, and AppSuite, which could be for used for applications belonging to a common suite. Guidelines for deciding what belongs in a project and when you should create a new project are discussed in section 5.2. Each StarTeam project consists of one of more views. Think of a view as a subproject it is a subset of the projects contents that support a specific activity. Every project automatically receives a main view into which folders, files, and other artifacts are initially placed. Additional child views are created to represent different 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 described in detail in section 5.3.
Borland Software
Page 24 of 90

3.4.2. Artifacts
The basic object-of-interest in StarTeam is an artifact.11 All artifacts are versioned, and some are branchable. All of the VCS concepts described in sections 2.1 (VCS) and 2.2 (SCM) apply to StarTeam: version numbers, branching and merging, sharing and cheap copies, etc. The built-in artifact types supported by StarTeam are summarized below: Folder: Every view has one root folder, which typically has a tree of subfolders beneath it. Folders are patterned from the file system concept of directories. In many cases, you will want to create StarTeam folders that mirror specific directory structures. However, StarTeam folders can hold any kind of artifact not just files. This concept may seem strange at first, but when you discover that you can organize change requests, tasks, and other non-file artifacts the same way you organize files, you will find this feature very powerful. Folders can branch, allowing the same folder to have different properties in each branch. File: StarTeam allows you to store any kind of file: text or binary, authored or generated, small or very large. A few more features are provided for text files such as keyword expansion and EOL conversion, but all file types otherwise are treated identically. With the 2006 release, StarTeam allows single file revisions larger than 4GB. (Now you know where to store your full-length movies!) Files are branchable, allowing parallel version streams and merging. Change Request: A change request (CR) is a general artifact that can represent a defect, enhancement request, or another reason for a software change. Because CRs are often the centroid of change management, the CR type is frequently extended with custom fields, custom GUI forms, and workflow rules. CRs can branch, allowing parallel modifications to the same CR for separate activities such as fixing the same defect in multiple releases. Using integration tools, you can import CRs from and keep them synchronized with other defect management systems. Task: StarTeam tasks are modeled after project management tasks: they can be arranged hierarchically to represent task decomposition, they can be connected with predecessor/successor relationships, and they can be updated with progress units known as work records. You can import tasks from a project management system such as Microsoft Project, update and maintain them via StarTeam, and then synchronize them back to the original project source. In StarTeam, tasks are versioned but they do not branch. Topic: A topic is very similar to a newsgroup message. Like newsgroup messages, topics can be organized into conversation threads. Because topics are artifacts, they are versioned (but not branched) and are stored in the repository with other artifacts. This allows you to capture more application lifecycle knowledge such as important discussions related to a design decision or a requirement approval.
11
In many StarTeam documents, an artifact is referred to by the overly general term object. In recent years, the term artifact has become generally accepted as the thing that versioning systems manage. So thats what we use in this document.
Borland Software
Page 25 of 90
StarTeam Best Practices Requirement: If you do not have a formal requirements management (RM) tool, StarTeam requirements provide a convenient, lightweight artifact with which requirements can be captured. Requirements can be arranged hierarchically to represent decomposition, and they can be linked to other artifacts. Since requirements are independently-versioned artifacts, they are more accessible than requirements buried in documents, which are versioned at the whole-document level. If you use a requirements management system such as Borlands CaliberRM, those formal requirements can be imported as StarTeam requirements and organized together with other lifecycle artifacts. (Borland provides integration tools to import, synchronize, and even link artifacts between StarTeam and CaliberRM.) Requirements do not branch. Audit: An audit is a read-only change event artifact that is automatically generated for other artifact changes: add, modify, delete, move, label attach, etc. Because audits are automatically generated and immutable, they are not really artifacts per se, but StarTeam allows you to access them with similar GUI and SDK techniques as other artifacts, so you can think of them as read-only artifacts. The generation of audits and the length of time that they are retained are configurable.
These artifacts are all bundled with StarTeam; however youre not obligated to use them all. The code for each artifact type is encapsulated in a dynamically-loaded plug-in module called a server-side component (SSC). Each SSC is a code library suffixed with .ssc that resides in the servers installation directory. If you rename an .ssc module before the server starts, the corresponding artifact type will not be used. For example, if you want to use StarTeam as a VCS only, just rename all *.ssc modules except for file.ssc. Note that you always get folders, so there is no .ssc module for it. Also, we recommend you keep audit.ssc due to the value of the change log represented by audit artifacts.
3.4.3. Artifact Versioning, Branching, and Merging
In sections 2.1.2, 2.2.2, and 2.2.3, we introduced the basic features of versioning, branching, and merging. In this section, well look at how StarTeam implements these concepts. In addition to a version number, StarTeam assigns each revision a dotted-decimal value called a dot notation. Whereas the version number is unique within a revision branch, the dot notation value is unique within the entire revision tree. An example is shown in Figure 7.
Borland Software
Page 26 of 90

dot notation
1.0
1.1
1.2
1.3
1.4
Main branch
0
version numbers
1 2 3 4
1.2.1.0
1.2.1.1
1.2.1.2
1.2.1.3
First branch created from revision 1.2

0 1 2 3
1.2.2.0
1.2.2.1
1.2.2.2
1.2.2.3
1.2.2.4
Second branch created from revision 1.2
0 1 2 3 4
1.2.2.1.1.0
1.2.2.1.1.1
1.2.2.1.1.2
New branch created from revision 1.2.2.1
0 1 2
Figure 7: Branching and Dot Notation
As shown, revisions on the artifacts main branch use the single dot notation pair 1.n where 1 indicates that it is the initial (first) branch and n is the same as the version number. When the artifact is branched from the main branch, revisions on the child branch use the dot notation 1.m.1.n, where m is the main branch version number from which the branch was created and n is the version number on the new branch. Note that an artifact can branch more than once from same point: in the example above, branches 1.2.1.n and 1.2.2.n were both created from main branch revision 1.2. The second 2 in 1.2.2.n tells you that this is the second branch from revision 1.2. Branch 1.2.2.1.1.n has three pairs of numbers, telling you that it is a third-level branch, created from parent revision 1.2.2.1. Artifacts that cant branch (tasks, topics, and requirements) are always on the main branch, so their dot notation is always 1.n. Now lets see how merging works. Recall that in merging, there is a source revision, a target revision, and a common ancestor revision that represents the latest source revision for which the source and target branches were reconciled. Suppose source revision 1.4 is merged with target revision 1.2.1.3. If this is the first merge from the 1.n branch to the 1.2.1.n branch, revision 1.2 is the common ancestor since it is the last revision that the 1.n and 1.2.1.n branches had in common. When the merge is complete, the merged result is added to the target branch, resulting in revision 1.2.1.4. This is illustrated in Figure 8.
Borland Software
Page 27 of 90

1.2 1.3 1.4
source branch
A merge point is stored indicating that source revision 1.4 is resolved with target revision 1.2.1.4.
common ancestor
source
Source revision 1.4 is merged to target revision 1.2.1.3. Source revision 1.2 is the common ancestor. New target revision 1.2.1.4 is created by the merge.
merge
MP
target
result
target branch
1.2.1.0 1.2.1.1 1.2.1.2 1.2.1.3 1.2.1.4
Figure 8: Merging Between Branches
After storing the merged result revision, StarTeam stores a merge point (MP) that points from the source revision 1.4 to the merged target revision 1.2.1.4. The merge point causes StarTeam to remember that these two revisions are resolved in that direction. If later we perform another merge between the same branches (in the same direction), StarTeam will pass revision 1.4 to the three-may merge tool as the new common ancestor. This allows the merge tool to more intelligently decide what new changes in the source branch should be merged to the target branch. Note that merge points are directional if we merge from the 1.2.1.n branch to the 1.4 branch, we create and use merge points that point in the opposite direction. OK, lets lift the hood on StarTeam artifact versioning just a tiny bit more so we can talk about object IDs. In a nutshell, all revisions in the same revision tree have the same root object ID (root OID). All revisions that belong to the same branch have the same object ID (OID). Furthermore, for all revisions on the main branch, the object ID and root object ID are the same. This is illustrated in Figure 9.
Borland Software
Page 28 of 90
OID=123 Version=0 (1.0) Version=1 (1.1) Version=2 (1.2) OID=311 Version=0 (1.1.1.0) Version=1 (1.1.1.1) Version=2 (1.1.1.2) OID=875 Version=0 (1.1.1.2.1.0) Version=1 (1.1.1.2.1.1) Version=2 (1.1.1.2.1.2)
Revision 1.x branch (OID = Root OID)
All revisions for file foo.java Root OID=123
Revision 1.1.1.x branch (OID Root OID)
Revision 1.1.1.2.1.x branch (OID Root OID)
OID=400 Version=0 (1.0)
All revisions for CR 413 Root OID=400
Version=1 (1.1) Version=2 (1.2) OID=573 Version=0 (1.2.1.0) Version=1 (1.2.1.1) Version=2 (1.2.1.2)
Figure 9: Artifact OIDs and Root OIDs
In this example, the file foo.java started with OID and root OID 123, and the corresponding 1.n branch has revisions up to 1.2. At revision 1.1, it branched to form the 1.1.1.n branch, which uses the new OID 311. Revision 1.1.1.2 was branched to form the 1.1.1.2.1.n branch with OID 875. But all revisions in the entire branch tree have the original root OID 123. Each revision holds the properties specific to it: name, description, contents, etc. Also shown is a change request (CR 413) that began with OID and root OID equal to 400. At revision 1.2, it branched (remember CRs can branch!) to form branch 1.2.1.n with OID 573. Now, consider a folder artifact. As youd expect, each revision holds properties such as name, description, and exclude spec (file patterns to ignore within working folders). Whats really different about StarTeam folder artifacts is that they do not have a property that represents their contents. Explaining how containment works leads us to items.
3.4.4. Items and Sharing
In StarTeam, the folder hierarchy and the contents of each folder are specific to each view. Artifacts can belong to (or more properly exposed through) any number of views and projects. An item is the object that both connects artifacts to a specific view and organizes them into a hierarchy. Figure 10 shows how this works.
Borland Software
Page 29 of 90

/foo Item /foo/a.txt Item /foo/b.java parent Item /foo/c.jar Item /foo/bar Item /foo/bar/c.jar Item /foo/bar/d.doc Item File d.doc Folder bar File c.jar shared file File b.java File a.txt
View
root
artifact
Folder foo
Figure 10: Connecting and Organizing Artifacts with Items
Every view has a root item, which always points to a folder artifact. In this example, the root folder name is foo.12 We can make any artifact in the repository belong to this folder by creating an item that points to both the artifact and the root item as its parent. In this example, the files a.txt, b.java, and c.jar and the folder bar are all child elements of the root folder foo. As you can see, the concept of path name is formed by concatenating the names referenced by the item structure. In this view, there is a file whose path name is /foo/bar/d.doc because we can get to this artifact via the item path: folder foo to folder bar to file d.doc. If we want to change the folder in which d.doc appears, we change the parent of its associated item the artifact itself is not modified. Notice that two items reference the file c.jar. This means that this file is contained in two different folders. We say that the file is shared in two places. This is analogous to Unix links that reference the same file, causing it to appear in multiple directories. Sharing allows any artifact to be shared in multiple places. Since artifacts are heavy (they contain all the properties) and items are light, this is how cheap copies are made: we just create items pointing to existing artifacts. Gee, this item versus artifact business sounds kind of complicated. Do we really need it? Actually, you mostly wont even be aware of the item/artifact dichotomy. StarTeam clients and the StarTeam SDK mostly blend the properties and behavior of the two constructs, exposing a single item concept. For example, in the SDK you can call Item.get("<property name>") where <property name> is either the name of a property belonging to the item (such as its parent folder) or to the artifact to which the item points (such as its name). You rarely need to think of the two as separate objects.
By convention, the root folder name is usually (but not always) the same as the view name. For this reason, in StarTeam URLs and other path specifications that include a project name, view name, and folder path, the root folder name is usually omitted.
12
Borland Software
Page 30 of 90
StarTeam Best Practices The most important things to know about items are summarized below: Artifacts can only be accessed through items: With StarTeam, you can only fetch or update an artifact by directing your request to a specific item. There are no commands to directly access an artifact independent of an item. This means that all artifact access is influenced by the context of the associated item such as its parent folder and the view in which it lives. Items form folder trees: Paths are formed by each views item tree. This means that folder artifacts do not define their contents. Instead, what appears inside a folder is determined by the items that refer to the folders item as their parent. You dont really move artifacts you move items. Moving an item from one folder to another causes the items parent to be modified the artifact referred to by the item isnt touched.13 This may seem strange, but it is a powerful feature well discuss further later. Items facilitate sharing: Items allow an artifact to appear in multiple folders, views, and projects. To make an artifact including its entire history appear in a new location, we only have to create a new item, which is pretty cheap. This is important to facilitate the concept of cheap copies discussed in section 2.2.4. Sharing is analogous to hard links used in Unix file systems. Items influence version behavior: An item has properties that control what artifact revision is referenced and how updates through the item are handled. Items store an OID that determines what artifact branch is referenced. An item also stores a configuration timestamp to indicate whether it floats to the tip revision or is pinned to a specific revision of the referenced branch. An items branch-on-change (BOC) flag indicates if the referenced artifact should branch when modified through the item. For example, if an item currently refers to artifact revision 1.7, and BOC is true, and an update is directed at the item, the artifact is branched by storing the updates to a new revision identified as 1.7.1.0. Additionally, the item is modified to point to the new branch (since it has a new OID), and its BOC flag is set to false. Note that BOC cannot be true for items that point to artifacts that cant branch (such as topics). Also, an item with BOC equal to false and a pinned configuration timestamp is read-only because we cant update a historic revision and we cant start a new branch! Items create promotion trees: This is an advanced concept, so well just touch on it briefly here. Items that are shared to a new location remember the item from which they were shared. This share parent relationship is different than the containment parent relationship that forms item paths. It facilitates a concept called automatic promotion, which well cover later.
Now that we know the difference between artifacts and items, which term should we use? It turns out that in most cases, either term works equally well. Because you can only access and update artifacts through items, and because StarTeam blends item and artifact properties into a single object (both graphically and in the SDK), you can think of them as a single concept. In the remainder of this document, well usually
13
Under the hood, items are versioned similarly as artifacts. This means that changes such as moving an item to a new folder really creates a new item revision, causing the previous item to become historic. Item versioning is necessary to make time travel work properly well discuss this more later.
Borland Software
Page 31 of 90
StarTeam Best Practices use the term item when we mean to include folder/view context that items add to artifacts. When the context is not important to the discussion, well use the term artifact.
3.4.5. Links and Process Items
A link is a binary relationship between two items. StarTeam links have configuration scope, which means that any two items in the same repository (regardless of project or view) can be linked. You can use links to form associations between artifacts for any reason: a requirement linked to a design document, a change request linked to a duplicate instance of the same defect, a task linked to a design specification, and so forth. Each endpoint of a link points to a specific item. An endpoint always stores the initial revision for which the link is valid; the link is not visible to revisions older than the initial revision. Additionally, an endpoint can be pinned to a specific artifact final revision or float to the latest artifact revision referenced by the item.14 A link also has a comment property that can be used to describe the link, why it was updated, and so forth. Links are versioned, which means that if you look at a historic configuration of a view, youll see the links as they existed in the historic snapshot. Links play an important part in the use of process items, which provide an intra-view change process mechanism. A process item is a CR, task, or requirement used as the context for a set of file changes. Process items can be used in any view for file add or check-in operations, but a project can define them as required for all of its views. Furthermore, project properties can define which artifact types are valid process items and which statuses are valid for each artifact type. In StarTeam clients, you can select an active process item, which means that it is used until its status becomes ineligible or another process item is chosen. Alternatively, you can select an eligible process item within each add/check-in dialog. StarTeam automatically creates links between a process item and any new files that are added or modified while the process item is in effect. Process item links are pinned at both ends. Consequently, the specific version of the process item used is linked to the specific version of each new or modified file. Example process items with pinned links are shown in Figure 11.
If youve been paying attention, you might be thinking Wait a minute if links point to items, how can an endpoint be pinned to a specific artifact final revision? An endpoint points to a specific item, but it also keeps data that says whether it floats to the items tip artifact revision or a historic revision. In other words, the endpoint sees one or more artifact revisions through the item, so it can be pinned to a specific one if we like.
14
Borland Software
Page 32 of 90

Process Items
CR 413 Version=0 (1.0) Version=1 (1.1) Version=2 (1.2) Link endpoint endpoint Link endpoint endpoint
Links
Files
File foo.java Version=0 (1.0) Version=1 (1.1) Version=2 (1.2) Version=3 (1.3) Version=4 (1.4)
Link endpoint endpoint Link endpoint endpoint
File bar.java Version=0 (1.0)
Task 1123 Version=0 (1.0) Version=1 (1.1) Version=2 (1.2)
File baz.java Version=0 (1.0) Version=1 (1.1)
Figure 11: Example Process Items with Links
In this example, the process item links tells us that CR 413 revision 1.2 created foo.java revision 1.2 and added file bar.java (since it is revision 1.0). At revision 1.1, task 1123 later updated foo.java to create revision 1.4, and baz.java revision 1.1 was checked-in on behalf of the task as well. Process items act like lightweight change containers. They provide traceability, allowing you to trace file changes to their purpose or context. They also provide a way to select file revisions created for a specific CR, task, or requirement so that, for example, you can attach those revisions to a view or revision label.
3.4.6. Labels
StarTeam labels facilitate what section 2.1.5 termed tagging. Labels provide a way to identify a specific set of artifact revisions for any purpose. Unlike containers such as views or folders, we say that specific artifact revisions are attached to labels instead of being contained by them. Furthermore, a label is usually fairly static the revisions attached to it are not expected to change much, if at all. A label provides a lightweight snapshot. Here is what is important to know about labels: View scope: Labels belong to a view. That is, each view has its own set of labels. This also means that every label has a name that must be unique from other labels belonging to the same view. Each label also has a description that helps users understand the purpose of the label. Frozen labels: A label can be frozen, which means no new artifacts can be attached to it, and attached artifacts can not detached nor reattached at a different revision. Conversely, non-frozen labels can have all of these modifications. Since many organizations depend on the immutability of frozen labels, a specific security permission is required to freeze or unfreeze a label.
Borland Software
Page 33 of 90
StarTeam Best Practices Labels attach items: StarTeam actually attaches specific item revisions to a label, each of which infers a specific artifact revision. Since each item defines a parent folder, the artifact is attached in a specific folder. This allows time travel to work properly, but it also means that if you move an item, you need to reattach it to any label for which you want to reflect the artifact in its new folder. View labels: StarTeam supports two kinds of labels. A view label is inclusive of the entire view as of a specific timestamp. That is, when a view label is first created, it is attached to every artifact revision that was tip as of that timestamp. (A snapshot of now can be used as the timestamp.) Dont worry; this is not as expensive as it sounds: StarTeam view labels are cheap. After a view label is created, new items can be attached to it, attached items can be adjusted to be attached at a different artifact revision, and items can be completely detached from it. A view label can be marked as a build label, which has extra semantics that assist build applications. Revision labels: The other kind of label StarTeam supports is a revision label. Revision labels are exclusive in that, when you first create them, nothing is attached to them. After you create a revision label, you attach specific items, building it up to reflect a specific set that is typically a small subset of the view. StarTeam can automatically attach new file revisions to a revision label at check-in time if you like. Label cloning: Even if frozen, both view and revision labels can be cloned. That is, you can create a new label starting out identical to an existing label and then adjust the revisions attached to it. A common practice is to clone a previous label, attach only new file revisions that were created to fix a bug, and use the new label as a new build candidate, or release candidate, or whatever.
Example view and revision labels are shown in Figure 12.
Borland Software
Page 34 of 90
View label Build 9.0.123
A view label points to all tip revisions as of a specific timestamp. Specific revisions can be attached/detached.
1.0
1.1
1.2
1.3
1.4
1.5
1.0
1.1
1.2
Artifacts
1.0
1.1
1.2
1.3
1.4
1.5
1.6
1.0
1.1
1.2
Revision label CR 413 Mods
A revision label points to specific cherry-picked revisions.
Time
Figure 12: Example View and Revision Label
Note that not all items in a view have to be attached to a label. Conversely, an item can be attached to any number of view and revision labels as you like.
3.4.7. Promotion States
Promotion states provide an intra view change management facility. Promotion states are built on top of view labels, providing an ordered set of states through which items can be promoted within a view. Promotion states are generally used to move the entire view (or most items within it anyway) through a series of steps based on passage of specific verification tests. After defining a set of promotion states and what view label each state is initially mapped to, you then periodically create new view labels to represent specific view states (such as daily build candidates). Depending on your process, you then typically map the lowest-level state to the new view label and launch the first verification test. After the tests for that state complete, you promote it, causing the next higher state to be mapped to that view label.15 (Multiple states often point to the same view label.) When the tests for the final or top most promotion state passes, the view is ready for release, deployment, or whatever your process calls for. Promotion states allow you can create build scripts, unit test scripts, deployment scripts, and so forth that operate on a specific promotion state without having to be modified to know about new view label names.
15
Dont confuse promotion state promote, which promotes items within a view, with the view compare/merge (VCM) promote action, which promotes item changes across views. VCM is discussed later.
Borland Software
Page 35 of 90
StarTeam Best Practices An example set of promotion states is shown in Figure 13.
Promotion States View labels, e.g., created by daily builds
Build 9.0.123
current label Release
Build 9.0.124
Integration Test Promotion causes next higher state to point to same view label Unit Test next higher state Build
Build 9.0.125
Build 9.0.126
Build 9.0.127
Build 9.0.128
Build 9.0.129
Figure 13: Example Promotion States
3.4.8. Miscellaneous Concepts
There are just a few other concepts we want you to know about StarTeam before we continue. They are: Working folders: These are workstation folders mapped to a particular view. Through the SDK, StarTeam clients match local workstations folders to the folder tree in each view. Normally, the client working folder tree follows the view folder tree precisely, but it doesnt have to.16 The SDK maintains local information that allows it to know the status of each working folder and file: not-inview (no match in the repository), missing (no match in the workspace), current (local and repository revisions match), and so forth. When you check-out files, by default they are placed in their matching working folders. Likewise, new files are added to the view folders that match their working folders. Working folders give rise to the notion of client-calculated properties such as status and size on disk. Time travel: This is another client-side concept that allows you to see what a view looked like at an arbitrary moment in the past. Normally, you see the current or tip configuration of a view. Every time you refresh the view (or, when MPX is enabled, when the view is automatically refreshed for
The ability to override the local working folder path for individual view folders should be used with caution. It can be handy when you need it, but use it sparingly to prevent confusion.
16
Borland Software
Page 36 of 90
StarTeam Best Practices you), you are seeing the latest items in that view. Time travel allows you to see the view as it existed as of a specific timestamp, view label, or promotion state. Artifacts revert to the revisions that were current as of that snapshot; moved items go back to their original folder; deleted items reappear; and so forth. Remember that a rolled-back view doesnt actually change anything at the server just your window into the view. Because a rolled-back view is historic, you cant change anything in it. (Sorry, cant erase your past mistakes!) However, you can check-out files from a rolled-back view to reproduce a previous build. In the graphical StarTeam clients, you can also share artifacts from a rolled-back view into another tip view window, including one that is the current configuration of the same view! (Hint: this is how you can recover a deleted file.) Security: Though we wont cover it in detail, StarTeam has a very comprehensive security facility. StarTeam uses a hierarchical rule scheme involving access control lists (ACLs) and access control entries (ACEs). An ACL connects one or more security principals (users or groups) to a protected object (project, view, folder, or individual artifact). Within the ACL, a set of ACEs define the permissions for those principals on behalf of the protected object. Because ACLs can be applied at multiple levels, say at both a view and folder level, the lowest-level ACL overrides higher-level ACLs. Best practices for administering security are discussed in section 6.3.2. Locking: StarTeam supports both shared (non-exclusive) and exclusive locks. Shared locks are useful if one or more users wish to prevent others from making changes to an item, for example if they depend on the current revision of a file but dont intend to modify it. An exclusive lock can only be held by one user and only when the item has no shared locks; it notifies others that someone is modifying an item. StarTeam also allows users (that have the needed permission) to break someone elses lock, which comes in handy when someone leaves on vacation and forgets to release their locks.
Borland Software
Page 37 of 90
4. Guidelines for Deploying StarTeam

This section discusses high-level options for hardware deployment with StarTeam. Because StarTeam can be used by small teams, enterprise-scale organizations, and everything in between, there are many options for deploying its components that affect performance, scalability, fail-over, and other factors. In this section, well just cover the basics. Where available, well provide references to other documents that provide more details on specific topics such as minimum hardware requirements, high availability options, and options for distributed teams. 4.1. Why Your Mileage will Vary The good news is that StarTeam is a rich application that can be used in a variety of ways. The bad news is that this flexibility makes it difficult to predict exactly what hardware configuration is perfect for your organization. Here are the major factors that affect the performance and scalability of a StarTeam configuration: Repository size: The number of views and items affect the StarTeam Server processs memory usage, database query traffic, and other resource factors more than any other type of data. Other kinds of data such as users, groups, queries, and filters have a lesser effect on resource demand. Simply put, as the repository gets bigger, more demand is placed on server caching and database queries. Concurrent users: The number of concurrent users during peak periods has a significant affect on a server. Each concurrent user requires a session, which maintains state, generates commands that utilize worker threads, incurs locking, and so forth. The number of defined users is not nearly as important as the number concurrent users during peak periods. If you use a single metric to gauge your repository size, use concurrent users. StarTeamMPX: MPX boosts server scalability, so whether or not you deploy it and whether or not clients enable it will affect scalability. MPX Cache Agents not only significantly boost check-out performance for remote users, but they also remove significant traffic from the server. In short, deploying MPX will bolster your configurations scalability. Bulk applications: On-line users that utilize a graphical client typically incur low demand on the server. In contrast, bulk applications such as extractors for StarTeam Datamart or Borland Search and synchronizers for integrations such as Borland CaliberRM or Mercury Quality Center tend to send continuous streams of commands for long durations. A single bulk application can generate demand comparable to 10-20 on-line users. Application complexity: Due to its customizability, StarTeam allows you to build sophisticated custom forms, add lots of custom fields to artifact types, create custom reports, and so forth. The more sophisticated your usage becomes, the more commands will be generated and the bigger artifacts will get, both of which increase demand.
Consider these factors when deciding the size of your configuration. Because of the unique factors that define your environment, take the deployment suggestions in this section as guidelines only.
Borland Software
Page 38 of 90
StarTeam Best Practices 4.2. What is a Large Configuration? The more sophisticated hardware deployments well recommend are those to support a large configuration. But what constitutes a large configuration? Many of us StarTeam enthusiasts have all StarTeam components deployed on a single laptop: a StarTeam server, an MPX Message Broker and Cache Agent, a workflow Notification Agent, a Borland Search server, and various StarTeam clients.17 Moreover, we often run these along side our IDEs, Office, and other tools. What this should tell you is that StarTeam components use resources proportional to the work they do. Memory, CPU, and other resources are consumed as the number of users and the volume of information grow. There are no hard rules about what makes a StarTeam configuration small, medium, or large. However, for our purposes, well use these definitions based on concurrent users: A small configuration is one that supports no more than 50 concurrent users. A medium configuration is one that supports no more than 100 concurrent users. A large configuration is one that supports 100 concurrent users or more.
Note that we didnt say anything about data volume or the type of users: on-line users or bulk applications. This is because, in our experience, the amount of data managed by a StarTeam configuration (particularly items) tends to grow proportionally with the number of projects and views, which grow in proportion to the team size. Moreover, the ratio of on-line users to bulk applications tends to be roughly the same across organization sizes. The concurrent user count seems to be the best metric for judging configuration size for purposes of deployment planning. So how big can a configuration get? To date, weve seen single StarTeam instances with over 500 concurrent users, over 10,000 total defined users, over 4,000 views, tens of millions of items, and up to a terabyte of vault data.18 With continuous hardware advances and software improvements, these limits get pushed every year. 4.3. What Happens When a Configuration Gets Too Large? StarTeam does not place hard limits on any of the factors described so far. Our philosophy (so far) is to allow you to add as many users, projects, items, etc. as you want, relying on hardware to keep up with the increase in demand. But realistically, there are limits to what you can do with hardware. There are costs incurred by increasingly growing configurations, and these costs eventually overtake the advantages of using a single configuration.
17
Some of us at Borland have multiple releases of these components installed and sometimes running all at the same time!
18
Note that not all of these limits have been reached by the same configuration. Although some customers have 4,000 views, not all are actively used. Our 500 concurrent-users customer had almost all on-line users. Interestingly, however, the amount of data managed by the vault seems to have little effect on performance or scalability.
Borland Software
Page 39 of 90
StarTeam Best Practices If you are the one charged with capacity planning, we want you to know what happens as configurations get really big. The negative effects youll see as a configuration grows are: Start-up time: The StarTeam Server process performs certain maintenance tasks when it starts such as purging aged audit and security records in the database. As the amount of activity and timebetween-restarts increases, these tasks increase the start-up time. Also, start-up time is affected by the number of unique share trees due to initial caches built at start-up time. With well-tuned options, even a large server can start in a few minutes, but it can also take up to 15 minutes or more. Memory usage: The StarTeam Server processs memory usage is affected by several factors such as the total number of items, the server caching option settings, the number of active sessions (concurrent users), the number of active views, and the number of command threads required. Caching options can be used to manage memory usage to a point, but sessions, active views, and other run-time factors dictate a certain amount of memory usage. On a 32-bit Windows platform, the StarTeam Server process is limited to 2GB of virtual memory. If you enable 4GT RAM Tuning19, this limit can be pushed closer to 3GB. Command size: Some client requests return a variable response size based on the number of items requested, the number of users or groups defined, the number labels owned by a view, and so forth. Large server configurations can cause certain commands to return large responses, which take longer to transfer, especially on slower networks. Clients will see this as reduced performance for certain operations such as opening a project or a custom form.
In short, be aware of these factors and consider the general affect they have as your configuration size increases. 4.4. Deploying Multiple Small Configurations on a Single Machine For small- to medium-sized server configurations, you can place all StarTeam server components on a single machine. Furthermore, you can also deploy all components for multiple configurations on the same machine depending on the sum of concurrent users of all configurations. This is illustrated in Figure 14, which shows both basic and MPX StarTeam components deployed. You should use a single machine for all StarTeam server components only when the total number of concurrent users for all configurations does not exceed 100. Even though a single configuration can support more than 100 users, each configuration has a certain amount of overhead. Consequently, we recommend that when the total peak concurrent user count reaches 100, its time to move at least one configuration to its own machine.
19
StarTeam is compatible with the Windows 4GT RAM Tuning option, which boosts the virtual memory limit of a single process on a 32-bit system. See the StarTeam administration documentation for details on using this option.
Borland Software
Page 40 of 90

Shared Server Machine
Root Cache Agent Client StarTeam Server process Database Root Message Broker Database Server Configuration #1
Vault
Client
Client
Configuration #2 Database
Client
StarTeam Server process Root Cache Agent
Client
LAN, WAN, VPN, etc.
Vault
Figure 14: All Server Components on a Shared Server Machine
With a single machine, all StarTeam Server processes, the root Message Broker, root Cache Agents, and the Database Server process execute on one machine. Here are some rules of thumb for this layout: Start with 1 CPU and 1 GB of memory for the database server process. Add 1 CPU and 1 GB of memory per StarTeam configuration. If you use locally-attached disk for each StarTeam configurations vault and database partitions, use separate, fast drives to improve concurrency. Also, the disks should be mirrored to prevent a single point of failure. (High availability is discussed in more detail later.) If you deploy MPX, all StarTeam configurations can share a single root MPX Message Broker. Though not shown, one or more remote Message brokers may be connected to the root Message Broker. If you deploy Cache Agents, each configuration needs its own root Cache Agent, which can share the root Message Broker. Though not shown, one or more remote Cache Agents may be connected to each root Cache Agent. Be sure to configure each StarTeam Server, Message Broker, and root Cache Agent process to accept TCP/IP connections on a different port.
Borland Software
Page 41 of 90
StarTeam Best Practices Using these guidelines, you can deploy 3-4 StarTeam small configurations on one machine, again only if the total number of concurrent users doesnt peak above 100 or so. Otherwise, the various processes could begin to compete for resources (CPU, memory, disk I/O, and/or network bandwidth), adversely effecting responsiveness. Also, if you start-out with the single-server configuration, dont forget to plan on moving components to their own machines when demand grows over time. One disadvantage of deploying multiple configurations on a single machine is that they are all affected when the machine must be upgraded, patches need to be installed, someone kicks the power plug, etc. 4.5. Deploying Medium Configurations As your configuration size grows beyond what could be called a small configuration, the first thing to move to its own machine is the database process. When you move the database process to its own machine, install a high-speed (1Gbit) dedicated link between the StarTeam server and database machines we have consistently found that this really makes the separation of the database to its own machine seamless. Using a separate machine for the database server, multiple StarTeam Server processes and MPX components can still be deployed on the same shared server machine. Because the database processing is offloaded to another machine, the total number of current users can be higher, up to 200-300 or so. A shared database server is shown in Figure 15.
Server Machine
Root Cache Agent Client StarTeam Server process Root Message Broker StarTeam Server process Vault
LAN, WAN, VPN, etc.
Database Machine
Configuration #1
Vault
Database
Client
Client
High-speed dedicated connection (1Gbit)
Database Server
Client
Database Configuration #2
Client
Root Cache Agent
Figure 15: Using a Separate Database Machine
In this diagram, locally-attached disk is assumed for the server and database machines. With multiple configurations, you have multiple vaults and databases, possibly on separate disks. As you consider backup Borland Software Page 42 of 90
StarTeam Best Practices procedures, mirroring for high availability, and other administrative factors, you may find it more costeffective to place all persistent data on a shared disk server (SAN or NFS). Many StarTeam customers with multiple configurations do precisely this. A shared storage server is shown in Figure 16.
Server Machine
Client StarTeam Server process Root Message Broker StarTeam Server process Root Cache Agent Root Cache Agent
Database Machine
Client
Client
High-speed dedicated connection (1Gbit)
Database Server
Client
Client
LAN, WAN, VPN, etc. High-speed fibre or network (1Gbit)
Vault
Vault
Database
Database
Storage Server
Figure 16: Using a Storage Server
Using a shared storage server for all configuration vaults and databases has several advantages. Depending on the storage system, all important data can be backed-up with a single procedure. Hardware to support mirroring or other RAID configurations can be concentrated in a single place. Many storage systems allow additional disks to be added dynamically or failed disks to be hot-swapped. 4.6. Deploying Large Configurations As mentioned before, we consider a large configuration one that supports 100 concurrent users or more during peak periods. For these configurations, you should place the StarTeam Server process on its own system. The database process should also execute on its own machine. Though not strictly necessary, the root MPX Message Broker and Cache Agent processes can also benefit by executing on yet another MPX machine. Especially when concurrent users rise to 200, 300, or more, moving the MPX processes to their own machine can remove network traffic and other resource contention from the StarTeam Server machine. A typical deployment of multiple large configurations is shown in Figure 17.
Borland Software
Page 43 of 90
MPX Machine
Client Root Message Broker Root Cache Agent Root Cache Agent
Client
Client
Server Machines
StarTeam Server process
StarTeam Server process
DB Machine
Client
Database Server
Client
LAN, WAN, VPN, etc. High-speed fibre or network (1Gbit)
Vault
Vault
Database
Database
Storage Server
Figure 17: Dedicated StarTeam Server Machines
The key points of this multiple, large configuration deployment are summarized below: The StarTeam Server process for each configuration executes on its own machine. This is typically a high-end machine with 2 CPUs/2GB of memory for 100-200 concurrent users and 4 CPUs/4GB of memory for 200+ concurrent users. If you expect the user base to grow over time, we recommend you start with the 4CPU/4GB machine. The database server executes on its own machine. Multiple StarTeam configurations can share the same database server. (Weve seen up to 8 configurations use the same database server without a performance issue.) Each StarTeam configuration uses its own schema instance. Each StarTeam server machine should have a high-speed (1Gbit) dedicated connection to the database machine. The MPX root Message Broker and root Cache Agents can all execute on a single MPX machine. Each root Cache Agent requires access to the appropriate vault, but a high-speed dedicated connection is not necessary. File access over the network (e.g., using UNC paths) is sufficient. Note that if you utilize the workflow Notification Agent, you can put it on the MPX machine as well. A shared storage server such as a SAN server can be used for all StarTeam vaults and database partitions. Depending on the hardware, an interface (e.g., host card) may be needed for each StarTeam server machine in order to access the SAN.
Borland Software
Page 44 of 90
StarTeam Best Practices 4.7. Clustering for High Availability In the white paper 24 x 7 StarTeam [Guck1], a graduated series of deployment steps is recommended that improve the availability of a StarTeam configuration. Each step reduces the likelihood of downtime and/or speeds the recovery from a failure, but at additional cost: training, software, or hardware. This approach allows your organization to make a return-on-investment (ROI) calculation that is right for it. Here, we want to highlight one topic from this paper. StarTeam works with active/passive clustering, in which a warm standby node is maintained for quick failover. One general rule to remember is that only one StarTeam Server process can be active for a given configuration at one time. However, StarTeam configuration files can be copied to multiple machines along with all the necessary software. Also, multiple machines under the control of Failure Management Software (FMS) can be connected to the same database (which may be clustered itself), and they can be connected to the same shared storage server for vault access. Active/passive clustering works like this: the StarTeam Server process on one node in the cluster is started, making it the active node for that configuration. The IP address of the active node is mapped to a virtual cluster address, which is the address to which clients connect. If the active node fails, the FMS takes care of failover: it starts the StarTeam Server process on a passive machine making it the active node and remaps the cluster address to the new active nodes IP address. Running clients receive a disconnect message and have to reconnect, but in most cases the failover will occur quickly, so clients can immediately reconnect. When you have multiple StarTeam configurations, you can pair machines so that an active node for one configuration is the passive node for a second configuration and vice versa. Hence, both machines are actively used, and only in a failover scenario one machine must support the processing of both configurations. An example active/passive cluster configuration is shown in Figure 18.
Borland Software
Page 45 of 90

To Clients
Cfg1 Virtual Cluster Address
Virtual to physical address mapped by FMS
Cfg2 Virtual Cluster Address
Failure Management Software (FMS)

Activated by FMS if Node 2 fails Activated by FMS if Node 1 fails
Node 1 ST Server ST Server Server (started) (stopped)
Cfg1
Cfg2
Cfg2 Cfg1 ST Server ST Server (started) (stopped)
Node 2 Server
Cfg1 Vault
Cfg2 Vault
Cfg1 Database
Cfg2 Database
Storage Server
Figure 18: Example Active/Passive Clustering
In this example, the StarTeam configurations Cfg1 and Cfg2 are paired; hence one node is active and one node is passive for each one. (The database process is not shown it might also be deployed on a cluster.) See the 24 x 7 StarTeam paper for more details and a deeper treatment of high availability topics. 4.8. Supporting Distributed Teams In section 3.3, we provided an overview of StarTeamMPX components. When users that access a StarTeam configuration are distributed geographically, MPX becomes essential for ensuring client responsiveness and server scalability. The white paper Optimizing StarTeam for Distributed Teams [Guck2] provides more details on deploying MPX and other techniques for remote developers. For quick reference, here are the highlights: Remote users should enable command compression to reduce the size of client/server messages. Remote users should enable both the StarTeamMPX Server and StarTeamMPX Cache Agent options. The latter should be set to automatically locate the closest Cache Agent. An MPX Message Broker and Cache Agent should be deployed in each geographic region with more than a few users. The StarTeam administrator should define MPX profiles to make it easy for users to select (once per workstation) the Message Broker that is geographically closest to them.
Borland Software
Page 46 of 90
StarTeam Best Practices Remote Message Brokers should be connected to the root Message Broker using a hub-and-spoke topology. Remote Cache Agents can be configured to auto-locate root Cache Agents as needed. Special options may be needed if Message Broker-to-Message Broker or Cache Agent-to-Cache Agent connections will traverse firewalls or VPNs. See the StarTeamMPX Administrators Guide for details on these options.
See the Optimizing StarTeam for Distributed Teams paper for more details and tips on deploying StarTeam for distributed organizations.
Borland Software
Page 47 of 90
5. Best Practices for Configuring StarTeam

In this section, we will explore best practices for using the primary StarTeam containers: configurations, projects, and views. The suggestions here are based on experience with successful StarTeam deployments, but treat them as guidelines there are good reasons to tune these suggestions to fit your needs. 5.1. Server Configuration: How Many Do You Need? As described in section 3.4, a StarTeam instance is known as a configuration. In terms of initial planning, one of the most important decisions your organization must make is how many StarTeam configurations it will use. This decision is important because changing your mind after you create projects and add artifacts is not easy. You can split up a configuration if it has become too large, but the process is complex. The procedure is described in section 5.1.5, but you can avoid having to use it by estimating project growth and considering interdependencies ahead of time. There are the primary benefits of having projects share the same configuration: Transactional integrity: Because a configuration uses a single database, all data within the same configuration is transactionally consistent. That is, a configuration represents a data consistency boundary. If you backup and later restore a configuration, all information within the configuration will be restored to the same point in time. Linking: Items in the same configuration can be linked, even if they are in different projects. StarTeam does not (currently) support cross-configuration linking. Sharing and moving: An item can be shared or moved to any folder, view, or project within the same configuration. Moving or items sharing across configuration boundaries is not supported. Administrative simplicity: Administrative tasks such as adding users and groups, applying security, performing backups, and so forth are done at the configuration level. Shared customizations: Many StarTeam resources such as filters, queries, custom forms, and workflows can be defined at the configuration level and shared by all projects. (However, custom forms and workflow can also be customized per project or per view.) Shared server components: All data in the same configuration utilize a single server process, database, vault, and root Cache Agent. New projects can be added dynamically without adding any new server-side components.
At the same time, there advantages of separating projects into separate configurations: Performance: For the reasons described in section 4.3, larger configurations take longer to start, use more resources, and tend to return larger command responses. Conversely, smaller configurations have less data and fewer concurrent users, so they tend to perform better in these regards.
Borland Software
Page 48 of 90
StarTeam Best Practices Managing growth: Even if you initially place multiple configurations on a single machine (as described in section 4.4), you can easily move a configuration to its own machine if you need to. Maintenance schedules: Separate configurations can be independently started and stopped for installing patches, upgrading hardware, etc. When a configuration is offline, all projects it contains are unavailable. Custom fields: Custom fields are added at the type level, which has configuration-level scope. This means that if you add a custom field to a CR, all CRs in that configuration will have a value for that field. Hence, if different teams or business units have competing interests in custom fields, this argues for placing their projects in separate configurations.
In addition to these pros and cons, the next sections describe additional factors to consider in deciding how many StarTeam configurations are appropriate for your organization.
5.1.1. Consider Business Unit Divisions
When multiple business units require their own StarTeam projects, it often works well to define StarTeam configurations along organizational boundaries. That is, deploy a separate StarTeam configuration 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, custom fields, and other issues. Separate configurations 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 5.2.2.
5.1.2. Leverage StarTeams Support for Distributed Teams
Team members that require access to the same artifacts should share a single StarTeam server. Dividing a StarTeam server solely due to geographically dispersed teams is not necessary. As described in section 4.8, StarTeam was designed to work well with distributed teams. StarTeam emphasizes a centralized configuration approach with MPX publish/subscribe messaging and Cache Agents to support distributed teams.
5.1.3. Dont Partition for Internal/External Access
In many situations, teams both behind and outside the corporate firewall require access to the same StarTeam configuration. A common practice in this scenario is to deploy the StarTeam Server process in the DMZ area of the firewall, placing the database server and storage 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. StarTeam provides SSL-like encryption for the command API, preventing eavesdropping on client/server traffic. All MPX Message Broker and Cache Agent traffic is also encrypted, making data private across public links. To limit access to specific teams, you can use reference views (described later) or StarTeams Borland Software Page 49 of 90
StarTeam Best Practices security ACLs to limit access to specific projects, views, folders, and even individual artifacts. Other security features such as strong password management and automatic account lockouts further increase the viability of using the same StarTeam configuration for both internal and external users.
5.1.4. Plan for Growth
In planning how many StarTeam configurations to create, take a long-term view: at least 3 to 5 years. If you can estimate concurrent user usage, this is the best metric for capacity planning. On todays hardware (a quad-CPU w/4GB memory), StarTeam readily supports up to 300 concurrent users. Some customers have configurations that peak at over 400 concurrent users, and one customer has seen peaks of 600 concurrent users. But at these concurrency levels, the application types become important (e.g., batch applications tend to demand more than on-line clients). Even a 300-concurrent user load may drive down responsiveness unacceptably if a substantial number of users are running high-demand applications. Another way to gauge configuration scalability is with command rates. You can measure the command rates of an existing configuration by using the server trace functionality. (See the StarTeam Server administration documentation for details.) The StarTeam server can be tuned to provide adequate performance with command rates from 200,000 to 300,000 commands per hour (56 to 83 commands per second). Command rates of 400,000 per hour (111 per second) or more with adequate performance have been observed with good network infrastructure (low latency). Attempts to drive a single configuration higher than this tend to produce unacceptable response times. If you cannot project user concurrency rates or command rates, you can use defined users, but the server load is less predictable using defined users alone. In geographically-distributed user communities, we typically see a defined-to-concurrent ratio around 10-to-1. So, we would expect 1,000 named users to yield about 100 concurrent user sessions during peak periods. In less-distributed topologies, where users are concentrated in 1 or 2 time zones, we expect the defined-to-concurrent ratio to be closer to 5-to-1. If you dont have better data, use these approximations to estimate your peak concurrent user rate. After estimating your 3-to-5 year projection, you should have an idea of how many StarTeam configurations will be needed to support your user community.
5.1.5. Splitting-up Large Configurations
If you have a large configuration that you want to split into multiple pieces, there is a procedure you can use. The basic process is to clone the configuration, change the GUID of the cloned copy, and then remove the projects from the original and cloned configurations that you dont need. Here is the basic procedure: 1) Perform a full dump (DB and vault) of the server configuration to be split. 2) Restore the database and vault on a secondary system. This is the cloned configuration. 3) Change the server GUID on the secondary system (ask Borland support for the process to do this). This requires both a database update and a change to the StarTeam server configuration file (starteam-server-configs.xml). 4) Delete the unneeded project(s) from the secondary system. 5) Run the StarTeam purge utility on the secondary system to clean-up deleted database records and vault files. Borland Software Page 50 of 90
StarTeam Best Practices 6) Verify the secondary system via VaultVerify, testing, etc. 7) Delete the unneeded project(s) from 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 weekend or other down time. If downtime must be minimized, a shortcut you can take is to hide the unneeded projects in steps 4 and 7 instead of deleting them. To hide them, change the security of the unneeded projects so that only an administrator can open them. This effectively disables them. Deleting large projects especially if there are lots of them and running purge can take many hours, so this shortcut can save lots of time. To some degree, the success of this process depends on the autonomy of the projects that you move to the cloned configuration. Shares between the moved and unmoved projects will reduce the amount of information that can be cleaned-up during the purge. This is one reason for keeping projects autonomous, which is discussed more in the next section. 5.2. Project Configuration: Defining a Projects Scope In software development, perhaps no term is more overloaded than project. Teams have projects. IDEs have projects. Virtually all ALM tools, including StarTeam, have projects. They are similar only in that they bound a shared set of information and/or activities. But what properly belongs to the same project depends greatly on the context. With StarTeam, when to create and how to organize projects are important decisions. The number of projects in a server and the number of artifacts managed in each affects issues ranging from performance to ease of administration. This section provides some guidelines for what belongs and what doesnt belong in the same StarTeam project.
5.2.1. Keep Projects Autonomous
The 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; construction phase artifacts such as source files, images, and resource files; and later-phase artifacts such as test scripts and applications.
Borland Software
Page 51 of 90
StarTeam Best Practices A project should include all artifacts authored in lifecycle phases as well as non-authored artifacts required for 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 projects IDEs or build processes. Input files may originate from third parties or from other projects in the same or other StarTeam configurations. (Deploying artifacts from one project to another is discussed 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. Using views to support specific lifecycle activities and releases is discussed in section 5.3. StarTeam works best when work artifacts (CRs, tasks, topics, and requirements) are stored in the same project as its files. 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.
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. We suggest that artifacts related to the same applications and components, even though of different types and/or lifecycle relevance should be managed in the same project.
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 artifacts required for all lifecycle phases of the client and server modules should be managed in the same project.
Borland Software
Page 52 of 90

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 clients artifacts. The latest header files and generated DLL needed by the Java client are checked into an external components folder by the build process used in the client/server project. All CRs, tasks, and other lifecycle artifacts related to the Java client are managed in the same project.
Example 3: A Complex 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; each of the five functional areas utilizes 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 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.
5.2.2. Handle Cross-Project File Dependencies
When 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 shared items 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.
Borland Software
Page 53 of 90
StarTeam Best Practices If a shared items 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 shared items branch-on-change property is set to true (perhaps accidentally), and a change is made to the child share, the artifact will branch in the child project. This severs automatic promotion of changes from the parent item to the child share. If the child share is a folder, an innocuous change such as modifying the working folder path will cause the folder object to branch. When an update is made to an item, the entire share 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 files are 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 files to be deployed are generated by the build. Keep in mind that checking-in the same file multiple times does not (generally) increase the size of the vault each unique file revision is only stored once. Configuration approach: Sometimes the codependent files dont 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 configuration file (e.g., XML) can be constructed that defines the files that participate in the 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 configuration 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 and possess no properties other than a link comment to identify their purpose.
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.
5.2.3. Support Cross-Project Activities
Regardless 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:
Borland Software
Page 54 of 90
StarTeam Best Practices 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. Section 6.2.6 also provides suggestions for using process items in combination with view compare/merge (VCM). 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 crossserver file metrics, your best option is to use StarTeam Datamart to harvest and report on CRs from multiple projects and even multiple configurations. Another option is to use the StarTeam SDK to write custom reporting applications.
5.3. View Configuration: Understanding View Types and Roles Recall from section 3.4 that a view is a window through which you can access a subset of the artifacts in a project. Furthermore, a view uses items to reference artifacts and manage access to them. Depending on how it is configured, a view can serve as a subproject for a specific development or maintenance activity; it can be a read-only or updateable subset of another view; or it can be used for other purposes. The good news is that views have tremendous flexibility to serve many needs. The bad news is that you can get unexpected or undesirable results if you dont understand how the different view types work. In this section, well first describe each view type, how it behaves, and when you might want to use it. Next, well describe views from the perspective of roles they can fulfill for specific development activities. Later, in sections 6.1 and 6.2, well describe practices for managing changes within a view and for propagating changes from one view to another.
5.3.1. View Types
StarTeam provides six view types. To understand taxonomy of these types, consider the view type hierarchy shown in Figure 19.
Borland Software
Page 55 of 90
View Type
Derived View
Reference View
Variant (branchable) View
Root View
Non-derived (blank) View
Updateable Reference View
Read-only Reference View
Branch-none View
Branch-all View
Figure 19: View Types
As shown, there are six concrete view types. Aside from the special root view type and one non-derived view type, the rest are derived view types, which subdivide into reference and variant types, each of which have two concrete types. The abstract and concrete view types are described below: Root view: A root view is the main view automatically created for each project. Initially, it receives the same name as the project, but you can change it. (Some customers like to rename it Main to emphasize its role.) When first created, the root view has only a root folder whose name matches the view. It is the only view type that has no parent it forms the top of the projects view hierarchy. The root view is the most important view in the project its role is discussed further in the next section. Non-derived view: This is also called a blank view. Like the main view, it initially has no items except for a root folder. Although a non-derived view has a parent view, it is not derived from that parent, which means it does not inherit the parent views items. You can add new items to it, or you can share items from other views into it. A non-derived view can be used for non-lifecycle activities, acting like a scratch pad that you build up item-at-a-time. You cannot rebase or promote a non-derived view via VCM, although you can replicate changes to/from it and another view in the same project. Derived view: A derived view begins life as a subset or an exact copy of its parent view. One of the parent views folders (often the root folder) is chosen as the root folder of the derived view; hence the derived view starts as a window into the artifacts at which it is rooted. What you can do with the artifacts in a derived view depend on whether it is a variant or reference view. Reference view: A reference view is a derived view that is a pure subset of its parent view. A reference view does not have its own items; it uses the same items as its parent view. Consequently, updates made to a reference view (if allowed) are applied to the same items used by the parent view. This also means that reference views never have their own artifact branches; hence reference views are also called non-branching views. Reference views also do not have their own view labels
Borland Software
Page 56 of 90
StarTeam Best Practices they share the same labels as their parents. Reference views are considered lightweight since they do not have their own items. A reference view can be updateable or read-only. Updateable reference view: An updateable reference view is a pure subset of its parent view with no added restrictions. If an item is updateable in the parent view, it is updateable in the reference view as well. Since the two views share the same items, changes in either view are immediately visible in both views. An updateable reference view is useful for exposing a portion of another view for security purposes. Instead of adding folder- and/or item-level security rights to the parent view, adding view-level security rights to an updateable reference child view is often easier to manage. Read-only reference view: A read-only reference view is a subset of items from the parent view that cannot be modified through the child view. A child view can float to the tip configuration of the parent view. In this case, it immediately reflects any changes made in the parent view to items it can see. Alternatively, a read-only reference view can be pinned to a specific configuration of the parent view: a timestamp, view label, or promotion state. A pinned read-only reference view reflects the state of the parent view (subset) as of that configuration. Once the child view is created, you cant change the configuration on which it is based. However, in the case of labels and promotion states, the child view will follow changes made to those objects. For example, if new items or different revisions are attached to the label or promotion state in the parent view, the child view will immediately reflect that change. Floating and pinned read-only reference views are useful when you want to subset a view and ensure read-only access, for example with applications such as build scripts. Variant view: Unlike reference views, a variant view is not a pure subset of its parent view. Although a variant view may initially be created as an exact copy or subset of its parent view, it has its own items. In fact, when a variant view is first created, the parent views items (or subset thereof) are shared (copied) to the child view, initially referencing the same artifacts. When new items are added to the child view, they are not automatically added to the parent view. Furthermore, since it has its own items, the variant views items may be independently configured, which means they could branch. Consequently, variant views are also called branching views. Whether or not a variant views items are initially marked branch-on-change (BOC) is the major difference between the two variant view subtypes. Branch-none view: If a variant views items are initially configured with BOC set to false, it is referred to as a branch-none view. It acts a bit like a reference view except that it doesnt share labels with its parent. If the child views items are created with a pinned configuration, they will be read-only. If the item configurations float, updates through those items will float to the parent. This is why a branch-none view is sometimes called a floating view. However, because the child view has its own items, moves in the child will not propagate to the parent view. Because of the discrepancy between the propagation behavior of moves versus other updates, branch-none views can be very confusing. 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, we recommend against using branch-none views. Branch-all view: Branch-all variant views are the most commonly-used views. A branch-all view begins life as a copy of its parent view (or subset thereof), with branch-on-change set to true for all items (that point to branchable artifact types). A branch-all views item can be configured to Page 57 of 90
Borland Software
StarTeam Best Practices float, causing changes in the parent view to float to the child view. However, branch-all views are far more useful when all items are configured to a specific timestamp or view label. Branch-all views are discussed more in the next section and in section 6.2. Of the six StarTeam view types, you will use main views and branch-all views with configured items (not floating items) the most. As detailed in the next section, each project will have only one main view, but you will use branch-all views to support both new development and maintenance activities. Reference views are occasionally used as a way to expose a read-only or updateable subset of its parent while simplifying security management. Blank views are rarely used, and branch-none views are not recommended.
5.3.2. View Roles
Technically, you only could manage a projects artifacts using only the root view. For example, you could: Add all new folders, files, CRs, and other items directly in the root view. Acquire locks as you modify items to prevent conflicts between users. Employ revision labels and process items to identify revisions related to the same logical change. Create view labels to mark milestones such as specific builds and releases. Use promotion states to propagate snapshots represented by view labels through a coordinated test and release process.
So why shouldnt you use this approach?20 Simply put: parallel development. The moment your team needs to work on two versions of the same file, module, or application at the same time, it needs a place other than the root view to do its work. This is the purpose of development streams discussed in section 2.2.6. You need containers that support parallel development or maintenance activities that require different artifact branches within the project. The child views you create under the root view provide these containers. Because version control and SCM products have existed for several decades, it should be no surprise that many different patterns have been developed for managing software development artifacts. (See for example [Berczuk].) These patterns affect the number of development streams you deploy and how you propagate changes between them. With StarTeam, this translates to the number and type of views you use and how they are organized. Most of the child views in your view hierarchy should be branch-all views. To determine when you need a new view, where it should live in the hierarchy, and whether a different type of view would be more appropriate, you should consider the role that each view will fulfill. Based on our experience, the best way to use views is to consider the roles described in the next sections.
20
Actually, when your project is just getting started, or if you have a very small (and safe) change to make, direct modification to the main view is fine. Otherwise, direct modification increases the risk of breaking the build if you havent staged your changes elsewhere first.
Borland Software
Page 58 of 90

Main View: Home Base for Artifacts
Because of its special importance to the project, hereafter well refer to the root view as the main view. The main view should contain the latest, approved revisions for the whole project. By latest, we mean that the main view should match your latest release, potentially extended with recent changes that are about to be released. By approved, we mean that it should contain revisions that have undergone whatever verification checks your process requires: a complete build, unit testing, integration testing, etc. By whole project, we mean that it should not be a subset of the projects modules. In short, your main view should contain the latest, complete, production work, ready to be seen and used by everyone. Implicit in this recommendation is that the main view should always be clean: buildable and able to pass most if not all tests. Experience has shown that you will avoid many headaches by keeping your main view clean. To do this, all except for the simplest changes should be made in other views where they can be tested and fine-tuned until theyre ready to be propagated to the main view. Once a new or modified revision has passed the point of no return youre sure you wont change your mind about only then should it appear in the main view. There is a subtle but important interaction between the main views and share trees you should be aware of. In general, the main view should contain the main (1.n) branch of each artifact. This happens automatically when you add a new artifact in the main view. (As discussed in section 3.4.4, StarTeam first creates a new 1.0 artifact and then connects it to the view and parent folder with a new item.) But suppose you create a new artifact in a child view and then share the item up to the main view. Since the child view item was created first, it will be the root share, and the main view item will receive a child share item (initially pointing to the same artifact). In other words, the item share tree will point in the opposite direction as the views. You probably wont notice a problem until you modify the item in the main view, causing it to branch, thereby pointing to a non-main branch (e.g., 1.n.1.m). In future attempts to propagate changes between the two views, youll find that it gets harder to propagate changes correctly because the share tree is backwards. For example, rebase operations wont work correctly. What can you do about this? The solution is to use the view compare/merge (VCM) facility to promote new items to the main view. VCM understands the share tree issue and propagates new items using an operation called reverse share.21 VCM is discussed in greater detail later.
Activity Views: Isolated Team Work Areas
Suppose your team is charted with developing a significant new enhancement (or a set of enhancements to be developed together). By significant, we mean changes that will affect more than a few artifacts, take more than a few days, and/or involve more than a few people. You wouldnt want to make changes directly to the main view since (a) you want to check in your changes often to ensure they are backed-up, progress can be tracked, etc., and (b) it may be a while before your changes are sufficiently stable to begin testing. The way to isolate your teams work is with an activity view.
21
Savvy StarTeam pre-2006 users are aware of this subtle share tree direction issue and employ custom solutions. Some customers simply add new items to the root view first and then share them down to child views. Other customers propagate new child view items to a parent view by first moving them up and then sharing them back down this is a basic version of what a VCM reverse share does.
Borland Software
Page 59 of 90
StarTeam Best Practices An activity view is a branch-all view created from a well-identified, stable configuration of the main view. If the enhancement work only requires a portion of the main views modules, you might choose to root the activity view from something other than the main views root folder. Typically, an activity view is created from a view label or promotion state, which causes it to contain items pinned to the same revisions in the main view as of that snapshot. As changes are made to the activity view, the corresponding items will branch and hence will not be visible to the main view. New items are also added to the activity view and hence not visible to the main view. As work progresses, the state of tip revisions in the activity view may not always represent a buildable release. But eventually, your team will build, test, fix, and finish its work, whereupon it is promoted to the main view. Activity views typically have a limited lifespan: when the enhancement work is done and promoted, they can be deleted, usually after a certain period of time. Strictly speaking, a single activity view could be used for multiple enhancement activities, but there is an advantage of using separate views for each activity: if for some reason the activity must be cancelled, the activity view can be abandoned and eventually deleted. This isnt practical if the view contains work from multiple activities. Either way, activity views periodically require rebasing, which is discussed later in section 6.2. A variation of the activity view is an integration view, which supports integration activities for a large software project. Integration views are described in section 6.2.5.
Release View: For Post-Release Maintenance Work
Assuming good stuff is happening in activity views and getting promoted to the main view, eventually you want to release something to customers. (After all, somebody has to fund our paychecks.) When you release a snapshot of your software, youll probably have to maintain a development stream just for hot fixes, patches, service packs, and so forth. A view that fills this role is called a release view (or a maintenance view). Like an activity view, a release a view is a branch-all view created from the main view as of a specific snapshot. Whats different about a release view is that it is created after one or more enhancement activities have been completed and promoted to the main view. Also, the release view is almost always rooted at the main views root folder, and it is usually created from a frozen view label to clearly establish the software configuration that was actually released. In fact, many organizations create the release view first and then build and deliver the software from the release view. Since it is a variant view, a release view can receive changes, e.g., to fix bugs. If these bugs must be propagated to the main view, they are promoted similarly as activity views. However, release views are generally not rebased to receive changes from the main view except for bugs fixed in the main view first that must be applied to the release view as well. Propagating changes to and from a release view is discussed further in section 6.2. If you need to make significant changes to a release view (perhaps a service pack), it is acceptable (even advisable) to create an activity view as a child of the release view. You would then make the changes in the activity view, perform appropriate validation tasks, and then promote it to the release view. You might even want to use a sandbox view, which is discussed next.
Borland Software
Page 60 of 90

Sandbox View: For Small Teams or Individuals
A sandbox view is similar to an activity view in that it provides a place where changes can be made without disrupting the parent view. A sandbox view is also a branch-all view created as a child of the view to which its changes are intended to be promoted. However, a sandbox view is different than an activity view in the following ways: A sandbox view is intended for use by a single individual or perhaps a very small team. Though not mandatory, the views permissions could be set so that only authorized users (and administrators) can open it. A sandbox view is often created for work on a subset of the overall project such as a specific module for which its owner is responsible. Consequently, its root folder may be created from a nonroot folder in the parent view. This makes the view faster to open and easier to navigate in graphical clients. A sandbox allows (and encourages) frequent file check-ins so that work is saved and can be tracked. The formal or informal rules for making changes are often relaxed. For example, checked-out files might not be locked; builds may be performed only on demand; and full testing and validation might only be performed only when changes are promoted to the parent view. As an alternative to the activity view, whose lifespan matches that of a fixed-length development activity, a sandbox view may be retained for a much longer period, spanning multiple tasks. In this role, a sandbox view is usually created as a child of the main view.
Sandbox views dedicated to individual developers are practical for small- to moderate-size teams. For large teams, instead of creating thousands of personal sandbox views, it is more practical to use activity views that are shared by multiple team members.
Build View: Read-Only Windows for Build Scripts
Many StarTeam customers create build applications using simple build tools (e.g., make, nmake) a commercial build product, or open source components (e.g., Ant, CruiseControl). It is easy to integrate these tools with StarTeam due to the availability of its full-featured SDK and the availability of pre-built components such as StarTeam Ant tasks and a CruiseControl bootstrapper plugin for StarTeam. Build applications typically open a view, specify a snapshot configuration (timestamp, view label, or promotion state), and then check-out the files they need. In some cases, however, an organization may want to restrict the access of the build tool (or user) in comparison to the permissions other users have to the view. For example, you may want to guarantee that (a) the build tool can only see artifacts required by the build (and not design documents or other artifacts), and (b) the build tool has read-only access and cannot modify anything. This situation could be handled through folder- or artifact-level security rights. However, this situation occurs often enough that some customers have found it useful to create a view tailored to the needs of the build tool. Such a build view is often created as a read-only reference view based on a promotion state. The reference view may be rooted at a non-root folder of the parent view. Consequently, a limited set of Borland Software Page 61 of 90
StarTeam Best Practices artifacts are exposed, they cannot be modified, and whenever the promotion state is assigned to a new view label, the new artifact revisions automatically appear in the build view. That is, the build view follows changes to the promotion state. Because security is easier to administer at the view level, a build view is often a more efficient way to accommodate build applications.
5.3.3. View Dos and Donts
Before we turn our attention to change management processes for using views, lets summarize a few last suggestions that apply to views in generals: As discussed earlier, try to ensure that items in the main view refer to the main (1.n) branches of its artifacts. Also, be careful not to delete the 1.n branch of an artifact unless it has truly achieved endof-life. Leaf-most views should be considered disposable. Eventually, when a views corresponding development activity is finished or its corresponding maintenance release is no longer supported, it should be deleted. This is important to prevent projects from growing unbounded, and it keeps the project structure uncluttered and easy to navigate. Deleting leaf views provides the StarTeam Administrator purge process with the maximum opportunity to actually shrink the database and vault by removing unneeded data. Three or four view levels in a project are normal. If you find your project has more than that, you might not be following best practices for views. For example, you may be making the mistake of performing new development work directly in the main view, forcing other active views to keep spawning child views. Or, you may be neglecting to promote the latest and greatest changes to the main view. Dont use branch-none (floating) views except in extremely rare cases when you understand exactly how they work. You can refactor projects that have become too big by moving items in the main view to another project. Old CRs, tasks, and other projects can be moved to an archive project so they can still be accessed without cluttering the main view of an active project. If you have a project with numerous modules or applications, a large number files can cause the time to select all descendants in the main view to take too long. You can break the project up by creating new projects and moving (not sharing) folders and items corresponding to whole components or applications from the old project to the new projects. Do this when the main view reaches a major milestone such as after a new release. If you want to refactor the project by reorganizing the folder tree, do this before you splitup the project. Create view labels before and after you refactor a project so you have markers for what changed.
Borland Software
Page 62 of 90
6. Best Practices for Common Processes

In this section, well discuss best practices for using StarTeam on an ongoing basis. The first section describes best practices for managing changes within a view. The second section discusses practices for propagating changes between views. Well end by providing some tips and techniques for administrative processes. 6.1. Change Management within a View Undoubtedly, your most active views will be the activity and sandbox views described in section 5.3.2. But, unless youve figured out how to write defect-free software, youll also need to make changes to release views. And, although we dont recommend it as a general practice, for small changes, it often makes sense to perform updates directly in the main view. In all of these cases, your team has several choices for the process by which the perform updates. The appropriate process depends on the size of your development team (which affects the probability of conflicts) and the level of detail with which you need to track changes. So, lets first review the ways in which changes are documented, tracked, and queried in StarTeam: Each new artifact revision can receive a revision comment where the user can document why the revision was created. Projects can be configured to require the revision comment for files. An artifacts revisions can be reviewed and compared in the History tab of the cross-platform client (CPC). Historic revisions include the revision comment, modifying user, modification timestamp, version number, and all other properties as of that revision. Starting with the 2006 release, the StarTeam cross-platform client (CPC) allows you to customize what properties are shown in the history tab. The StarTeam 2006 CPC also allows you to compare file content changes in a dedicated file compare pane (discussed later). Unless audit generation has been disabled for the configuration, an audit record is generated for both revision-generating changes and other updates such as moving an artifact to a new folder or attaching an artifact to a label. You can query audit records in the CPCs Audit tab. The length of time that audit records are retained is configurable via the StarTeam Administrator. We recommend that you always enable audit generation and retain records for at least 90 days. Through process items or explicit actions, links can be used to connect work items such as CRs and tasks to files added and modified on their behalf. Links generated via process items are pinned to the specific artifact revisions involved at both ends. You can view an artifacts links in the CPCs Link tab.22 Artifacts can be attached to revision and view labels so that revisions related to a common task or milestone are easily identified. (StarTeam can automatically attach new and modified files to a
22
Another new feature for the 2006 CPC is the ability to navigate to an artifact from the Link tab. Just click on a link in the Link tab and click Select linked item from the context menu.
Borland Software
Page 63 of 90
StarTeam Best Practices revision label at add/check-in time.) The artifacts attached to a label can be seen in the CPC by selecting Select -> By Label. The labels to which each artifact revision is attached can be seen via the CPCs Label tab. The CPC offers several text-based reports and graphical charts for reporting on historic revisions, links, audit records, and other information. You can also create custom report templates that can be saved and reused. All of the change information described above can be accessed via the StarTeam SDK. If none of the built-in reporting mechanisms are sufficient for your needs, you can build custom reporting tools or applications. Custom tools can even be centrally stored and automatically downloaded to CPC users, where they can be activated via the toolbar. The StarTeam Datamart product allows information from a StarTeam project, configuration, or multiple configurations to be extracted and loaded into a relational database, which can be queried and analyzed through reporting and business information tools. Borland Search is a search engine product that indexes and provides secure searching of multiple StarTeam (and CaliberRM) repositories. It can search across space (repositories, projects, views, and folders) and across time (historic revisions). All searching honors the security of the harvested artifacts; hence, it provides another way to find all the stuff your organization is storing.
Now that weve looked at the primary means by which you can report on changes within a view, lets look at ways in which you can manage change. Well do this by examining three scenarios in increasing order of formality.
6.1.1. Scenario #1: Working in a Small Team
If youre working on a project managed by a small team, you may not need much formal change management. Furthermore, if code modules are clearly assigned to individuals, or if you can just lean out your office door and yell, Hey, Im working on the report module, then the possibility for conflicts may be very low23. In this case, your change process may be very simple: Maintain a set of local working folders where you keep the latest files for each view. Before you begin a new development task, get your working folders up-to-date by checking out any Missing or Out of Date files.
23
Its not that conflicts are necessarily bad since StarTeam detects them and helps you resolve them gracefully. However, lots of unexpected conflicts will slow your team down, so you want a process that minimizes them or handles them at planned integration phases.
Borland Software
Page 64 of 90
StarTeam Best Practices As you modify files in your working folders, youll see their status in the CPCs File tab become Modified. New files will appear as Not in View because they have not been added to the view yet. New folders will appear as Not in View in the Folder tab.24 When youre ready to check-in, refresh your window (if you dont have automatic refresh turned on) to see if another developer added or modified anything that may affect you. Check-out any new Missing or Out of Date files. If another developer checked-in a file that you modified locally, its status will become Merge. The best way to resolve the merge conflict is to check-out file and click Yes to the Do you want to merge question. This will launch the bundled or configured three-way file merge tool.25 If there are no conflicts, the merge tool usually just saves the merged result file over your existing work file. Otherwise, you may be prompted to review and tweak the result file before continuing. Once saved, the files status will change to Modified. When you have only Not in View and Modified files, to do a build, run unit tests, and/or do any other validation steps your team requires. Finally, commit your changes to the view. You can select all of the new (Not in View) and modified files and check them all in at once.26 One caveat of adding new files and checking-in modified files in the same check-in dialog is that the revision comment is also used to initialize the description property of new files. If you want accurate descriptions for new files, add each one separately or modify each files description after adding it. New folders are added automatically you only need to explicitly add new folders on the server when they are empty on the client.
And thats it. You get revision history and audit records automatically. This process doesnt fool with labels, and you dont get process item links either. But it might be all that your organization needs. As Einstein said, Everything should be made as simple as possible, but not simpler.
6.1.2. Scenario #2: Preventing Merge Conflicts
As your team size grows, the problem you may find with the previous scenario is encountering too many unexpected merge conflicts. Your team may want everyone to know when youre about to make changes
24
If you used pre-2006 releases, yes we did just say Folder tab. In the 2006 CPC, a Folder tab has been added that shows folder properties, including a workspace status property with values Not in View, Current, and Missing. (Its about time!) And, if you enable Show Not-In-View Folders in the Folder Tree menu, youll see not-in-view folders in the folder tree regardless of which tab is selected. The folder tree always shows Current folders and those Missing from your workspace.
25
If you previously used the bundled StarTeam diff/merge tools, be sure to try out the new File Compare Merge tool included with StarTeam 2006 it is a major advance in file diff/merge functionality. Another change for StarTeam 2006: if you add and/or check-in multiple files in a single step, they are now committed as an atomic transaction. Moreover, file content is pushed to the server outside of transaction state in a restartable manner. So, if you cancel a large multi-file add/check-in operation before it commits, you can restart it by just doing it again only files that didnt make it in the first attempt will be sent to the server. The commit happens at the end only when all content has arrived using a single transaction.
26
Borland Software
Page 65 of 90
StarTeam Best Practices to a file before you actually do so. To better communicate intent and reduce the likelihood of merge conflicts, you can amend the process outlined in the previous scenario as follows: In the CPCs personal options, set the options Mark unlocked working files as read-only and Clear file locks on check-in. When you want to edit a file, lock it via the CPC first. (In some IDEs with StarTeam integrations, when you attempt to edit a read-only file, the IDE will offer to lock the file for you.) The lock will notify others that youre editing the file. When you check-in modified files, the CPC will automatically unlock them for you (in the same transaction in which the changes are committed).
This process both informs team members of who is working on what, and it minimizes merge conflicts. Note that your team can require this process by setting the project-level options Require exclusive lock when files are checked-in and Mark unlocked files read-only. Its up to you and your team to decide if you want this level of enforcement. Note that in this scenario, we still arent using labels or links yet
6.1.3. Scenario #3: Using Process Items
The next step in a more formal intra-view change management practice is to use process items so that all file modifications are linked to an appropriate work item. You can enforce the use of process items at the project level using the Process Rules options. These options let you: Require the selection of a process item when new files are added or modified files are checked-in. Select which item types are eligible as process items. Your choices are CRs, tasks, and requirements. Specify whether or not the status of each item type will be considered in order to be used as a process item and which status values are permitted. For example, you can specify that CRs must have a status of Open, but tasks can be used regardless of status.
When you enforce process items, existing files cannot be modified and new files cannot be added until an eligible process item is selected. Consequently, new and modified files are automatically linked to the selected process item, enhancing the context information of these changes. Moreover, the links are created in the same atomic transaction in which the file updates are performed. Note that in the add and check-in dialogs, you can elect to mark the selected process item closed (CRs), finished (requirements), or complete (tasks). If you choose this option, the process item update is also performed in the same atomic transaction. Another advantage of process items is that you can use them to define the scope of a VCM session in order to propagate the changes to another view. This is discussed further in section 6.2. But we still havent engaged labels Borland Software Page 66 of 90

6.1.4. Effective Use of Labels
The change tracking aspects of the previous scenarios can be enhanced by using labels. In any change process, you can use revision labels to tag a set of artifacts related to the same change, and you can use view labels to identify snapshots of the entire view that represents specific milestones. Using revision labels is very simple: In the file add and check-in dialogs, enter a new revision label name in the Revision Label box (or select one from the drop-down if you already created the label elsewhere). Call it something descriptive such as CR 413 fixes. All new and modified files will be attached to it. You can also attach non-file artifacts to a revision label, and you can attach revisions that you consider part of the same change set even if you didnt modify them. For example, you could attach the specific revision of a design document that you referred to. To see what files are attached to a revision label, from the context menu, select Select -> By Label and choose the revision label. The files attached to the label will be selected. You can leave these items selected and then lock them, attach them to a view label (more on that in a moment), or generate a report that lists them (e.g., Reports -> Summary). If you modify a file more than once and attach it to the same revision label, be sure to select the option Move the label if its already assigned to a previous revision in the check-in dialog. Otherwise, the label will not be reattached to the new revision youre checking-in. If you move a file or other item after attaching to a label and you want the label to remember it in its new folder, be sure to re-attach it to the label.
Revision labels can denote whatever boundary of work you want: a single CR fix, a set of tasks, a large enhancement, etc. Like process items, revision labels can be used to define the scope of a VCM session in order to propagate the changes to another view. This is discussed further in section 6.2. View labels should be used to mark configurations of the entire view that match specific milestones such as a new build number, a point from which another view was created, a release candidate, and so forth. Consequently, you dont create or use view labels for specific check-ins. Instead, you create them when one or more changes have been committed and its time to launch a new build, spawn a release view, or promote changes to another view. Here are two scenarios that illustrate good uses of view labels:
Scenario #1: Daily Builds
Whether your team prefers daily builds, nightly builds, hourly builds, or builds on demand, this approach creates new view labels where Use as build label is selected: To get the process going, first create a view label as of a specific timestamp and launch the build process. (Some users prefer to have the build process itself create the view label.)
Borland Software
Page 67 of 90
StarTeam Best Practices The build process then check-outs files attached to that label and launches compiles, links, and other build tasks. If these tasks are successful, the same build process could also launch unit tests and other verification tasks. If all build tasks are successful, the view label could be marked as frozen, which identifies it as a good build. Conversely, if a build task fails, the build process could generate a report or notify someone via email. If youre early in the development activity, you might choose to just move forward, allowing the team to continue making changes in the view. The next build process will simply try it again. When youre later in the development activity, youll want to have the appropriate developers fix their errors, re-attach the new revisions they create to the same view label, and perform the build again. Only when you achieve a good build is the view label marked frozen.
The advantage of this approach is that it tends to ensure that the tip revisions in a view are generally buildable. This supports a growing software development practice known as continuous integration. The disadvantage of this approach is it may be difficult with large teams and environments with lots of changes. It can result in a lot of broken builds, finger pointing, and nasty gram emails.
Scenario #2: Change Builds
Instead of relying on tip revisions being generally stable and buildable, another approach is to create view labels that are attached to revisions that are carefully selected. The steps that take this path are outlined below: Assume you start with an existing good build view label. As with the previous scenario, this label would be flagged as a build label and probably frozen. Although many changes are occurring in the build, you want to select only specific changes as candidates for inclusion in the next good build label. To do this, ensure that the corresponding file revisions are attached to a revision label and that this label is only attached to the file revisions youre interested in. Start the next good build label by cloning the current label. In the CPC, select View -> Labels -> View tab -> New. In the corresponding dialog, choose Labeled configuration and select the current good build label. Your new label will now be identical to the old label. Select the file revisions associated with the desired changes. In the File tab, select Select -> By Label and choose the appropriate revision label. Now attach these revisions to the cloned view label. In the File tab, select Labels -> Attach. In the corresponding dialog, select the cloned label in the upper label list. In the Attach to items at group box, select Labeled configuration and choose the same revision label you used in the previous step. This ensures that the correct revision of each file is attached to the cloned label otherwise the tip revision will be attached, which may be the wrong revision.
Borland Software
Page 68 of 90
StarTeam Best Practices Repeat the previous two steps if there are multiple revision labels representing file revisions that should be included in the new label. Now launch the appropriate build and test process for your new good build label. Mark the label frozen or reattach fix revisions and retry as in the previous scenario depending on whether the build/test process succeeds.
This approach allows you to tag view configurations as candidates for builds, promotes, etc. without relying on the tip revisions being stable. The disadvantage of this approach is that if your latest good build label is way behind the views tip configuration, the quality of more recent changes may not be known for a while (which goes against the premise of continuous integration.) Because this approach employs label cloning, there is a caveat we should mention with respect to deleted items. Suppose an item is attached to a view label and then deleted from the view. As youd expect, when you time travel by adjusting your view window back to the view label, the item reappears because it existed when it was attached to the label. Less obvious, however, is that when you clone the label, the item will also be attached to the new label because the new label is initially identically to the old label. If you dont want items deleted in the tip configuration to be attached to a cloned label, just detach them from the cloned label.
6.1.5. Miscellaneous Tips
To finish our tour of same-view change management practices, here are some miscellaneous tips, some of which strengthen key points made before: Use revision comments: Revision comments are allowed for all artifact types, not just files. They often get over-looked, but they are quite useful. They appear in property dialogs, item panes, the History tab, certain expanded keywords, and various reports. You can make revision comments for files required via a project-level option. Consider keywords for source files: Keywords are $-bounded tags that you can add to source files. Keyword expansion is enabled at the project level for specific file extensions. StarTeam looks for keywords in applicable files during check-out and expands them, inserting text that auto documents the file. In the StarTeam 2006 release, the $History$ keyword was added as a better alternative to the $Log$ keyword. The $History$ keyword allows faster file check-outs and will be expanded even for Cache Agent-based check-outs. Use revision labels: We have found that revision labels are underused, yet they are inexpensive and very handy. Tagging all revisions related to a logical change using a revision label is especially useful with VCM. Enable the File Compare pane: In the 2006 release, a file compare pane was added to the CPC. When you enable it (via the Tools menu), file comparisons are automatically displayed in a separate compare pane in a variety of situations. For developers, this provides a quick way to review file changes. The File Compare pane automatically compares files in the following contexts:
Borland Software
Page 69 of 90
StarTeam Best Practices When you select a file in the item pane, the File Compare pane displays the differences between the tip revision of the file and the file in your working folder. When you select two files in the item pane, the File Compare pane displays the differences between the tip revisions of the selected files. (If the files are very dissimilar, the comparison can be, shall we say, entertaining.) When you select a file in the item pane and one revision in the History tab, the File Compare pane displays the differences between the selected historic revision and the file in your working folder. When you select a file in the item pane and two revisions in the History tab, the File Compare pane displays the differences between the selected historic revisions. When you select any item in the item pane (say a CR) and a link in the Link tab that is linked to a file, the File compare pane displays the difference between the linked file and its previous revision. (If the linked file is the first revision, no comparison is displayed.) If the link floats to the tip revision of the file, it displays the difference between the tip and previous revision. For links created by process items, this shows exactly what was changed on behalf of the process item!
An example of the CPC with the File Compare pane displaying differences between two historic revisions of a file is shown in Figure 20. Note that the File Compare panes context menu is shown this menu provides access to many useful compare options.
Borland Software
Page 70 of 90
Figure 20 - Example of the CPCs File Compare Pane.
6.2. Change Management across Views For most views, changes need to be propagated to another view sometimes several views at key milestones. When work is complete or reaches a suitable release point in an activity or sandbox view, you need to merge it up to the parent view. When a bug is fixed in the main view, it may need to be propagated down to one or more release views. Sometimes you need to propagate a fix sideways, from one release view to a sibling release view. Prior to the 2006 release, StarTeam provided several graphical and command-line tools for propagating changes between views. One of the most significant enhancements for the 2006 release is the replacement of these tools with a completely new facility known as view compare/merge (VCM).27 VCM is now your primary tool for propagating changes from one view to another. Because it is new and represents a major advance in change management for StarTeam, were going to take a fairly deep dive with VCM.
27
OK, the name is not very exciting, but trust us: VCM is a significant improvement in the science of change management.
Borland Software
Page 71 of 90

6.2.1. Overview of VCM
VCM is a new cross-view change management facility for StarTeam 2006, replacing the previous view compare/merge tools. VCM represents a substantial advance in change management functionality and flexibility. It is the premiere tool for propagating discrete sets of changes from one view to another. VCM uses a session concept: a session is a specific VCM operation that can be started, reviewed, adjusted, verified, and then committed. No data is modified in the StarTeam repository until the session is committed, at which point all changes are applied at once. Before a VCM session is committed, it can be saved and restored potentially on a different machine. This allows scenarios wherein one user creates the session and then transfers it to a peer for review or to verify the session before committing it. Two StarTeam views are involved with every VCM session: The source view contains the changes to be propagated. You can use the tip configuration of the source view or a snapshot defined by a view label, promotion state, or timestamp. There are several ways to identify the items to be considered for propagation, collectively known as the source scope. If you like, the entire view can be used as the source scope, though you will usually propagate items that represent specific changes. The target view receives the propagated changes, so it must be updateable. Receiving the changes does not mean that the source items are merely copied to the target view as-is. VCM compares the source view to the target view and determines if and how to propagate item differences. Propagation of a specific change can take many forms such as sharing, re-pinning, merging, and so forth. You can review and adjust what VCM proposes before anything is committed.
The VCM facility is available through two application interfaces:28 The CPC provides a graphical interface that is integrated with other CPC functionality. For example, you can select an item, folder, or group of items in a regular view window and start a VCM session using the selection as the source scope. The VCM Utility is a command-line tool that allows you to start, resume, and commit VCM sessions from shell scripts. In a single script, for example, you could create a VCM session, perform a test build of the proposed changes and run other verification tasks, and then commit the session if all tests complete OK.
The CPC interface allows user interaction with the entire VCM process. The VCM Utility provides partial or complete automation of VCM sessions, which can be helpful when a specific kind of session is performed repeatedly. VCM sessions are interoperable between the two interfaces. For example, you can create and save a session using the VCM Utility and then restore, review, and commit the session using the CPC.
28
Both interfaces are merely front-ends to the VCM engine, which resides in the StarTeam SDK. The VCM engine API is not publicly exposed as of the 2006 release, but it may be in a later release.
Borland Software
Page 72 of 90
StarTeam Best Practices Every VCM session has a specific merge type, which controls the direction and semantics of the VCM session: Rebase: A rebase session propagates changes from a parent view (the source) to an immediate child view (the target). The most common use of rebase sessions is to catch-up a child view with changes that occurred in the parent since the child view was created or since the last rebase was performed. Promote: A promote session is the opposite of a rebase: it propagates changes from a child view to its immediate parent. Promote sessions employ special rules that accommodate the directionality of share trees. That is, they strive to keep share trees pointing in the same direction as the projects views. (See the discussion for the Main View in section 5.3.2.) Replicate: A replicate session propagates changes from a source view to any other (updateable) view in the same project. Compared to rebase and promote, replicate is the wild card merge type that allows changes to be propagated anywhere in the same project.
Note that with all merge types, the source and target views must belong to the same project. All VCM sessions follow the same basic process, which is outlined below: 1. Definition: The session is defined in terms of its merge type, the source view (and snapshot), the target view, the source scope, and various options. In the CPC, a session is started from a View Compare/Merge menu option, available in several places, which launches a wizard dialog. The context from which the wizard is launched affects the definition of the session. In the VCM Utility, the session is defined by command-line arguments and/or an options file. Both the CPC and VCM Utility provide a variety of ways to define the source scope items. The source scope can be the file revisions linked to one or more process items (and optionally the process items themselves); the items attached to a revision label; items of specific types that reside in selected folders; a set of cherry-picked items; and items of selected types in the entire view.
2. Comparison: Once a session starts, VCM first performs the compare phase. In scope source items are matched to corresponding items in the target view. VCM detects both simple changes (items that are new, modified, or deleted in one or both views) and more complex changes (items that have been moved, renamed, modified-and-moved, etc.) For an item that exists in both the source and target view, VCM uses information such as merge points to determine if either item or both have changed since the last time they were merged. For each difference found, VCM defines an item difference that specifies the source and/or target item (sometimes there is only one of these) as well as a default action. The action Page 73 of 90
Borland Software
StarTeam Best Practices specifies what the session will do about the item difference. Many actions are possible including ignore, move, merge, delete, reverse share, move and merge, etc. 3. Review: After the comparison phase has completed, the results can be reviewed, adjusted, and validated before the session is committed. VCM provides a preview of what the target view would look like if the session was committed in its current state. The CPC provides this preview as a test perspective. The VCM Utility provides a CheckoutPreview option that allows you to check-out files from the preview. In both applications, you can generate a difference report, which summarizes all item differences and their current actions. Actions are considered resolved if no user input is required to continue. However, unresolved actions such as differences with merge conflicts require user input the session cannot be committed without user attention. As a best practice, all actions should be reviewed and adjusted if necessary. Some differences have multiple possible actions. For example, for an item in a merge state (modified in both views since the last compare), you could choose to overwrite the target item to match the source item instead of choosing to merge the two. Using the preview, you can resolve conflicts, adjust actions if necessary, check-out files to working folders, perform a build and run tests, and so forth.
4. Save and restore: Optionally, at any time after the compare phase, you can save the VCM session and restore it later. Restoring a session resumes the session at the same point at which it was saved. A session saved as a VCM Session file (.vcms file extension) is a shortcut that can only be used to restore the session on the same computer. This is because temporary files are saved on the workstation required to resume the session. A session saved as a VCM Exchange file (.vcmx file extension) is a self-contained change package file that can be copied to another computer, emailed, checked into StarTeam or added to a CR as an attachment, etc. Others can then restore, review, and even commit the session.
5. Commit: When the session has been tested, adjusted, reviewed, etc., it can be committed. Only at this point are updates applied to the target view. Based on session options, various labels can be automatically created that document what changed in the target view. View labels can be created that provide a snapshot of the target view before and/or after the updates were applied. Revision labels can be created that are attached to target view items affected by the VCM session before and/or after the updates were applied. VCM can also generate a post-commit update report, which enumerates exactly what was changed by the session. Page 74 of 90
Borland Software
StarTeam Best Practices Now that weve covered the basics of VCM, lets delve into how and when to use each of the various VCM merge types.
6.2.2. When to use each VCM Merge Type
Each of the VCM merge types is intended to be used in specific scenarios. Using VCM for the right scenarios is important because the VCM uses different rules for handling differences depending on the type of merge.29 Below is a description of the intended use for each VCM merge type.
Rebase Merges
Use a rebase merge to catch-up a child view with changes that have occurred in the parent view since the child view was created or since the last rebase. An example rebase scenario is shown in Figure 21.
Parent View
(3) In parallel, changes are made in the parent view. (4) A rebase is performed to propagate parent changes to the child view. (6) Another rebase is performed to propagate new changes.
mod
mod
mod
mod
Child View
mod mod
(5) More changes occur in both views in parallel.
mod
mod
mod
(2) Changes are made for the activity: modified files branch; new files are added; files are moved, renamed, etc. (1) An activity view is created from a specific label, promotion state, or timestamp for an enhancement.
Figure 21 - Example VCM Rebase Scenario.
In this scenario, an activity view is rebased twice to update it with changes that occurred in the parent.
Promote Merges
Use a promote merge to deliver changes in a child view to its parent. You could promote once at the end of the child views lifecycle as a prelude to discontinuing work in the child view. However, you can also promote multiple times to periodically deliver changes from the child view to the parent. In either case, it is typically a good idea to rebase the child view just prior to promoting it to ensure it has accepted (been merged with) all recent changes from the parent view. An example promote scenario is shown in Figure 22.
More specifically, VCM uses a rules engine where merge type is one of the conditions used to detect item differences and choose default actions. You can actually alter the rules used by the engine via the DefaultAction option in the VCM Utility.
29
Borland Software
Page 75 of 90

(2) A promote is performed to release child changes to the parent view. (6) Compile and test went OK, so the child was promoted to the parent again.
Parent View
mod
mod
Child View
mod
(4) Meanwhile, the parent was also modified.
(7) The activity view went end-of-life after that.
mod
(3) Oops! More changes were needed in the activity view.
(5) A rebase catches-up the child with the parent.
(1) An activity view has been created, modified, rebased, compiled, tested, and is ready to be released.
Figure 22 - Example VCM Promote Scenario.
In this scenario, the child view is promoted twice and retired (no longer used) after the second promote. Typically, youd want to delete a retired view after a period of time. (See section 5.3.3.)
Replicate Merges
Use a replicate merge to propagate a change when the target view is not an immediate parent or child of the source view. An example replicate scenario is shown in Figure 23.
Parent View
(2) Changes are made (e.g., via promotes) in preparation for the next release. (4) More changes are made for future releases.
mods
mods
mods
Release 2.0 View

(1) A release view is created to support the 2.0 release.
patch
(5) A bug is fixed in 2.0 that is applicable to 3.0, but not other releases.
Release 3.0 View

(6) A replicate is performed to duplicate the patch from the 2.0 view to the 3.0 view.
(3) A release view is created to support the 3.0 release.
Figure 23 - Example VCM Replicate Scenario.
Borland Software
Page 76 of 90
StarTeam Best Practices In this example, a bug fix must be propagated from one release view to another, but the release views are old with respective to the tip revision of the parent view and not applicable to it. Consequently, it makes sense to merge the fix sideways, directly from the source view to a sibling target view.
6.2.3. Using VCM with a Simple Project
Now lets look at some full lifecycle scenarios using VCM for cross-view change management. Suppose you have a small project and a small team, making it is generally safe (i.e., not disruptive) to perform new development directly in the main view. The only other views you may need are release views for maintenance purposes. In this scenario, your primary use of VCM is to propagate patches from or to the release views. An example of this is shown in Figure 24.
Main View
mod
check-out with lock check-in with process item and unlock
mod
mod
mod
mod
mod
Release 1.0 View

Release view created from view label when 1.0 milestone reached
A release 1.0 patch is promoted to the main view
patch
and propagated to the 2.0 release via a rebase
Release 2.0 View

Release view created from view label when 2.0 milestone reached
patch
patch
Release 2.0-only patches
Figure 24 - VCM Usage with a Simple Project.
In this scenario, you perform all new development with direct modifications in the main view. When a release milestone is reached, you create a view label as the reference point for defining a release view. To fix bugs in a given release, you make changes directly in the release view. If you make a patch in one release that must be propagated to the main view and another release, first deliver it to the main view via a VCM promote and then propagate it to the second release via a VCM rebase. (Alternatively, if the patch did not apply to the main view, you could use a VCM replicate to propagate it directly from one release view to another.)
Borland Software
Page 77 of 90

6.2.4. Using VCM with Activity and Sandbox Views
In most circumstances, direct modification to the main view is not advisable due to the potential instability it may cause. As discussed in section 5.3.2, activity and sandbox views provide a place where development can occur without disrupting the stability of the parent view. These view roles also provide a way to discard work when there is a chance that it could be cancelled and never delivered to the main view. The primary difference between activity and sandbox views is scope: activity views generally have longer life spans and serve a group of developers; sandbox views generally have short life spans and serve an individual developer or a very small team. However, there is no reason an activity view cant be used for short-term work or a sandbox view cant be used for long-term work. When activity and sandbox views are used, all new, fully-verified and approved changes should make their way to the main view. Release views should be created from the main view to provide streams for maintenance work. It even makes sense to sometimes create a release view from another release view, for example when a dot release will be shipped then maintained separately from its parent release. An example of recommended VCM practices with activity and sandbox views is shown in Figure 25.
Short-term views end after final promote
Main View Short-term Sandbox View
Long-term views rebase/promote many times
Short-term Sandbox View
Release 2.0 View
Long-term Sandbox View
Long-term Activity View

Release-to-release replicates
Release 1.0 View
Release 1.1 View

Figure 25 - VCM with Activity and Sandbox Views
In this example, two short-term sandbox views are created from the main view. (The mod and patch cycles shown in the previous example are omitted here to reduce clutter.) After these views work is complete, they are promoted to the main view and become inactive (and eventually deleted). A long-term activity view and a long-term sandbox view are also shown. These views live beyond a single release; hence their work may be promoted to the main view several times. Shown in the example is the recommended best practice of always rebasing a view just prior to promote it; this causes the child view to merge changes from the parent so they can be integrated and tested.
Borland Software
Page 78 of 90
StarTeam Best Practices This example also shows release 1.0 and 2.0 views being created from the main view, but a release 1.1 view is created as a child of the release 1.0 view. Also shown is a patch made in the release 2.0 view and being back ported directly to the release 1.0 and 1.1 views via a replicate merge.
6.2.5. Using VCM in High Concurrency Projects
Suppose you have a large project involving many sub-teams, each developing a separate component of a final application or suite. You may find it impractical to have each team use its own activity view and then integrate the changes in the main view. The integration and stabilization of large projects can be lengthy, causing long periods of instability in the main view, which is as a bad thing. To address the needs of large development projects, we introduce the notion of an integration view. An integration view is a branch-all view that is positioned between the main view and one or more activity views. When the time is right, the grandchild activity views are promoted to the integration view, where integration testing occurs. When the integration view passes all applicable tests, it is finally promoted to the main view, delivering its changes. An example using integration views is shown in Figure 26.
Main View
Integration View
Release View
Activity View 1
Activity View 2
Activity View 2
Figure 26 - Using Integration Views for Large Development Projects
Notice that the integration view is created first as a child of the main view. An activity view for each major component or sub-team is then created as a child of the integration view. The reason for creating the integration view first as a parent of the activity views is so that VCM promote merges can be used to propagate changes from the activity views. Promote is the best merge technique for new development because it uses rules that are designed for propagating changes up the view hierarchy. For example, new items are reverse-shared instead of shared, causing the parent view to take ownership of the main (1.x) artifact branches. If the integration view was created after the activity views, it could not be their parent, so youd have to propagate changes with VCM replicate, which uses share as the default action for new items instead of reverse-share. If changes occur in the main view while work is done the activity views, the activity views should periodically be rebased to accept those changes. However, they can not be rebased from the main view Borland Software Page 79 of 90
StarTeam Best Practices since it is not their parent. Instead, you must rebase the integration view first. Rebasing the integration view should be very easy no merge conflicts should be found since no changes should occur directly in the integration view until the integration work is ready to begin. After an activity view has been rebased, it can be promoted to deliver its changes to the integration view. You could immediately retire an activity view once it has been promoted, choosing to resolve any integration issues and fix bugs in the integration view. However, for complex integrations, you may choose to promote, rebase and adjust, then promote an activity view several times. Eventually, though, you should shift the integration effort to the integration view since it has the big picture. When the integration view passes all tests, promote it the main view, create a release view, and pop the champagne.
6.2.6. VCM and Process Items
In the construction phase of software development, your team will expend the most effort on creating and modifying files. Often this work will be directed by process items CRs, tasks, or requirements that define specific units of work. During integration testing and post-release maintenance, process items should be the predominant device for managing changes. Process items are recommended for identifying logical groups of changes because the corresponding links support traceability. When you use VCM, how should you handle process items? Should you enter CRs, tasks, and requirements directly in the views that will use them? Or should you create them in the main view and move them to the view where they will be used? If you use a process item to check-in files related to a unit of work, should you use the same CR, task, or requirement as the process item in the target view for the VCM session that promotes or replicates the same work? There are variations on valid practices that you can use, but here are best practices that weve found:
Process Items Should Be Single-Purpose
If you use a process item to fix a bug or create an enhancement in one view, you shouldnt use the same process item for any other work in the same view or another view. One reason for this is a technical restriction on links: a link cannot simultaneously point to different revisions on the same artifact branch. This means that if a CR has a link to a file in one view and you attempt to link the same CR to the same file in another view (by using it as a process item), the second operation could alter the original views links. These undesirable side-effects effectively corrupt the original process item links. Another reason for keeping process items to a single purpose is for change tracking: each logical change operation should utilize its own process item. If a CR is used to track a bug fix operation, promoting that bug fix to another view is a separate change; hence the VCM operation should use a different process item. These arguments mean that a process item used to manage work within a view should not be used to propagate the same work across views. You should create a new process item such as a task for the VCM operation; the task could have a meaningful description such as Promote CR 413. If you need to promote the same changes to multiple views, say from an activity view to an integration view and then to the main view, have VCM create a post commit revision label and use it to define the source scope of the second VCM operation. Then, create another task or other process item for the second promote.
Borland Software
Page 80 of 90

Where Should Process Items Be Created?
If you know where the work will be performed at the time you create a process item, create it in the corresponding view. If you dont know ahead of time where work will be performed, create the process item in the main view. Then, when the work begins, move (dont share) the process item to the view in which the work begins. This allows the process item to be used for files added and modified on its behalf, linking them to the process item. But if this complicates your status reporting, read on
Simplified Work Status Reporting
If you use VCM to propagate changes but the process items used for specific bug fixes and enhancements are stored in child views, how can you easily report on the status of all unfinished work? You could use StarTeam Datamart to harvest information from the whole project and report on open CRs, tasks, etc. You could also write a custom application that traverses active views looking for this information. Either of these may be acceptable solutions in some organizations, but there is another approach that gives you timely work status information without writing a custom application. The basic process is as follows: 1) When new work (bug, enhancement, requirement, etc.) is identified, always create the definitional CR, task, or requirement in the main view. 2) When the view in which the work will be carried out is identified, create a task in that view for use as a process item. (You could use a CR instead, though we believe a task has the best semantics.) The task should have a meaningful name such as Fix CR 1123 or Implement Requirement 529. To improve traceability, link the task to the definitional item defined in 1). Use the task as the active process item while checking-in new and modified files, causing them to be linked to the task. When the task is complete, mark it as Finished. 3) If there is more than one view in which work is required, repeat step 2) for each of them. In fact, you could create all of the work tasks before any work actually begins, linking them all to the definitional item in the main view to make it easier to monitor the child view work as it progresses. 4) When the work in a child view is ready to promote to the main view, use the work item (or multiple work items) from the same view to define the VCM source scope. That is, start the VCM wizard in the CPC by selecting the work item(s) and clicking Advanced -> View Compare/Merge. In the wizard, include the linked files (i.e., check Files linked to selected <item type>, but dont include the work item itself. In the VCM commit dialog, select the definitional item defined in step 1) as the process item. This will cause all new and modified files to be linked to it. 5) After the changes from all applicable views have been promoted, mark the definitional item as closed, finished, etc. This process keeps all the primary work items in the main view, allowing you to use filters, queries, reports, and charts to report on the status of active items. For any specific item, you can generate the Links report to see items promoted to the main view on its behalf. If you link work tasks created in step 2 to the primary work items, you will see them in the report as well. You can customize the Links report to show the properties most important to you. Borland Software Page 81 of 90
StarTeam Best Practices 6.3. Administrative Processes Compared to other client/server systems, StarTeam does not require much in terms of administration. The administrative tasks youll need are pretty much what youd expect: backing-up configurations, adding new users, and performing periodic health check-ups. In this section, well describe some tips and techniques for administering StarTeam configurations.
6.3.1. Performing Online Backups
Even if you used mirrored disks and other fault tolerance techniques, you should backup each StarTeam configuration daily. Some files such as the server configuration list (starteam-server-configs.xml), MPX profiles (MPXEventTransmitter.xml and MPXFileTransmitter.xml), and Cache Agent configuration files only need to be backed-up when they change. But we suggest you include them in your daily backups so that you have everything need to restore a configuration in a single backup. A StarTeam configuration can be backed-up while it is in use; you dont have to lock or shut-down the StarTeam Server process. The most important thing to ensure a transactionally-consistent backup is to back-up the vault after the database. When a backup is restored, its OK if the vault backup has extra files not reflected in the database, but you dont want a restored database to reference vault files that arent restored. Here is a process for a safe, on-line backup procedure: 1. First backup the configurations database using the databases online backup procedure. Both Oracle and SQL Server have online backup procedures. 2. When the database backup is complete, perform an online backup of the configurations attachment folder and each hives archive folders. These backups can be performed in parallel, and a full/incremental backup schedule can be used such as: 2.1. Perform full backups weekly 2.2. Perform incremental backups daily In both the attachments and archive files, new files are only added existing files are not modified. Consequently, you can speed-up the backup process by using a differential copy utility that detects and backs-up only new files added since the last backup. Periodically, however, you should perform a full backup so that recovery does not require too many backup copies! For a comprehensive backup procedure, be sure to keep a copy of StarTeam installation media, license information, and other important configuration information in an offsite location.
6.3.2. Managing Security
Not many people consider managing security settings as fun. So, here are a few tips aimed at minimizing the time you spend administering security: Keep things simple: Perhaps the biggest mistake some administrators make is trying to get too sophisticated with security settings. Yes, you can create ACLs all the way down to the item level,
Borland Software
Page 82 of 90
StarTeam Best Practices but over time this can be very time-consuming. Instead, try to manage security at the project and view levels. Avoid micro-managing security at the folder and item levels. Secure groups, not users: Add security rights to groups, not individual users, and then assign users to the group(s) to which they belong. Butdont go overboard defining groups or youll still be micro-managing. Define groups in terms of roles: project manager, architect, build meister, etc. Use reference views to subset: If you need to grant access to a specific folder tree within a view, consider creating an updateable reference view that subsets the tree instead of using folder-level security. This allows you to manage view-level security on both the reference view and the parent on which it is based. Read-only reference views and non-derived (blank) views can also be helpful in some cases to subset another views artifacts for security purposes. Use the LDAP integration: Although StarTeam has built-in security management, you can delegate authentication for individual users to your LDAP server. This delegates not only password verification but password aging, password strength management, and other account management to your LDAP server. This keeps you out of the reset my password business. However, be sure to maintain a non-LDAP administrative account or two in case you need to logon when LDAP isnt working!
For a deeper understanding of StarTeam security and more tips, be sure to read the white paper StarTeam Security Explained! [Sauers]
6.3.3. Monitoring Server Performance
The StarTeam Server process should be monitored for significant changes in performance characteristics. The larger the user community is for a given configuration, the greater the need is for monitoring performance. Why monitor for performance changes? Basically, youre watching for two things: Capacity planning: As your repository size or concurrent user set grow, the servers demand for resources will also grow. You want to watch for the need to add more resources such as more memory or increased network bandwidth. Degradations: Network cards can become flaky; database indexes can become unbalanced; disks can become fragmented; and so forth. You should watch for unexpected hardware errors and other degradations that may affect your user community.
There are many tools you can use to monitor the performance of a StarTeam configuration. Here are some examples: Process monitoring: Use a process monitoring tool such as Microsofts PerfMon or Sysinternals Process Explorer to monitor the StarTeam Server process. Key metrics to watch are CPU Usage, Private Bytes, and Context Switch Deltas. Sharp, sustained increases in these metrics could indicate a resource starvation issue. Secondarily, you should monitor process handles, I/O bytes read, and I/O bytes written. If you graph process metrics over time, pronounced changes in usage could indicate resource issues that need investigation.
Borland Software
Page 83 of 90
StarTeam Best Practices Network monitoring: Using a commercial network monitor application, its worthwhile to monitor both the client-facing and database-facing traffic with the StarTeam server machine. We have seen customers experience unexplainable performance issues only to find their network was out of gas. Database monitoring: Using SQL Servers or Oracles profiling tool, monitor for queries and stored procedures that run for more than five seconds. Occasional instances of these are probably OK, but if you start seeing a lot of them, you could have a resource starvation issue on the database machine or possibly an index optimization/statistics issue. (See the next section.) StarTeam Server commands: Via the StarTeam Administrator, you can configure the StarTeam Server process to generate a trace file of some or all commands that it executes. (See Configure Server -> Diagnostics.) If you set the value for Trace operations that take longer than to zero, every command will be traced. Borland can provide you with an application called TraceDump, which converts the generated trace (.trc) files to a comma-separated value (.csv) format. These can then be loaded into a spreadsheet or simple database for analysis. In particular, you can see command execution times broken down by function: total time, queue time, CPU time, database time, etc. If you take periodic snapshots of command times for you environment, watching for trend changes can tell you if users are experiencing performance issues.
Another possibility is to write a custom SDK application that periodically runs and performs a specific set of operations: connecting to the server, opening a project and view, fetching a CR, and so forth. This provides a user level indicator of performance that you can track over time.
6.3.4. Tuning Server Performance
Some aspects of StarTeam server performance can be fine-tuned through configuration options. Here are the primary knobs that you can turn: Caching Options: These options are specified in the server configuration file (starteam-serverconfigs.xml). The option names follow the format <ItemType>sCaching (e.g., FilesCaching, ChangeRequestsCaching) and can have values 0 through 2. When the caching value for an item type is set to 0, no additional caching is performed for items of that type. When the value is set to 1 or 2, items of that type are cached in memory, resulting in greater performance for accessing items of that type at a cost of increased server memory. Threads Options: The options MinCommandThreads and MaxCommandThreads are also specified in the server configuration file. They control the number of command threads used by the StarTeam Server process to process client requests (commands). As of the 2006 release, the min value is ignored; the server uses a fixed number of threads set to the max value, which defaults to 16. In large StarTeam configurations, you should boost the maximum command threads to gain optimal concurrency. Values between 32 and 64 are optimal for configurations with 200 peak concurrent users or more. When the number of command threads is too low, you will see the queue time of commands increase in the StarTeam command trace files (see previous section). Audit Log Options: Options affecting the generation of audit records are found in the StarTeam Administrator (Administration -> Configure Server -> Audits). As previously discussed, it is highly recommended that you enable audit generation. For medium to large configurations, you should Page 84 of 90
Borland Software
StarTeam Best Practices also enable audit purging to prevent audit record from growing unbounded. We suggest setting the audit age to at least 90 days. Setting the audit age to larger values increases the time to perform certain queries in the CPCs Audit tab. Security Log Options: Options affecting the purging of security event records are found in the StarTeam Administrator (Accounts -> System Policy -> Security Events). For medium to large configurations, we recommend that you enable the purging of security records. Maintain at least 90 days of records. Setting the retention value to a large value increases the time to query the security log in the administrator tool (via Accounts -> Security Log). Inactivity Timeout: Setting this value via the StarTeam Administrator (Administration -> Configure Server -> General) causes the server to close connections that have no activity after a specified period of time. This helps free-up connections, memory, and other resources for active users. Vault Hives: By default, each StarTeam configuration begins with a single hive in the vault. In configurations with very large vaults, you can increase disk I/O concurrency by adding a second hive to the vault. Hives can be added via the StarTeam Administrator either while the server is stopped or dynamically while it is started. You can also dynamically add a vault hive if the existing hive is getting low on space and another disk volume is available for expansion.
See the StarTeam administration documentation for more information on these options.
6.3.5. Maintaining Configuration Health
Independent of performing back-ups and monitoring performance, there are a few other things you should do to maintain the health of your StarTeam configurations: Database maintenance scripts: Review the StarTeam administration documentation about running database maintenance scripts. StarTeam provides scripts for both SQL Server and Oracle that perform tasks such as rebuilding indexes and updating optimizer statistics. These tasks are essential for maintaining query performance as the database grows. Vault Verification: Periodically, you should run StarTeams VaultVerify utility to check for corrupt or missing archives in your vault. Archives could become missing if the configuration is recovered from a database and vault backup that are not transactionally consistent. Archives can become corrupt if a virus detector automatically cleans a virus from a vault file. VaultVerify can be run in check mode while the configuration is in use; it can attempt to repair errors if the StarTeam Server process is stopped. Purging old data: Your StarTeam configuration will grow unbounded unless you take steps to get rid of old, unneeded data. As described in section 5.3.3, unused leaf views should eventually be deleted. Similarly, obsolete projects should eventually be deleted. However, these operations do not actually remove vault files or database records. Periodically, you should use the StarTeam purge tool, which shrinks the size of the vault and database by removing information linked to deleted views and projects. The purge process can take several hours on large configurations, so schedule this process during off hours. Page 85 of 90
Borland Software

6.3.6. Maintaining a Test Server
With medium to large configurations, there are probably some changes that youd rather not make for the first time to your production server. For example, new custom forms and workflow rules can take some fine-tuning before theyre ready for the general population. Adding custom properties may also warrant testing since they are difficult to delete once they are added. New custom StarTeam applications, especially those that perform updates, could also benefit from having a test area. A great way to address these needs is to maintain a test configuration as a recent copy of your production. The basic procedure for cloning a configuration is described in section 5.1.5. Youll want to perform the steps that restore a backup copy of your production server and change its GUID, though you dont need to delete any projects. Changing the GUID is important so that you dont have two servers in the same environment claiming to be the same configuration. Periodically, toss the test server and restore it from a recent production backup so that it contains recent data. Then, use it as a guinea pig for new forms, workflow, and applications. The test server is also a good place to train new users becoming familiar with StarTeam. Another advantage of the test server concept is that it causes you to verify that your backup and restore processes are working!
Borland Software
Page 86 of 90
7. References
[Berczuk] Berczuk, Stephen P. and Appleton, Brad; Software Configuration Management Patterns: Effective Teamwork, Practical Integration; Addison-Wesley Professional; 1st edition (November 4, 2002) [Guck1] Guck, Randy; 24 x 7 Borland StarTeam A practical look at high availability; http://www.borland.com/resources/en/pdf/white_papers/starteam_24_x_7.pdf; January, 2005 [Guck2] Guck, Randy; Optimizing Borland StarTeam for distributed teams The best techniques for supporting distributed teams; http://www.borland.com/resources/en/pdf/white_papers/optimizing_starteam_for_distributed_teams_w hite_paper.pdf; January, 2005 [Sauers] Sauers, Ron; StarTeam Security Explained!; http://bdn1.borland.com/borcon2004/article/paper/0,1963,32233,00.html; September, 2004 [Spolsky] Spolsky, Joel; Good Software Takes Ten Years. Get Used To it.; from the web site Joel on Software; http://www.joelonsoftware.com/articles/fog0000000017.html
Borland Software
Page 87 of 90
8. Glossary
access control entry (ACE) access control list (ACL) A set of access rights (such as the ability to read, create or delete) granted or denied by an ACL. A security rule that grants or denies permissions defined in an ACE to a security principal for a specific object. ACLs are defined on objects hierarchically (project -> view -> folder -> item); hence, the lowest-level ACL found in an objects ancestry that matches a given user is the one that applies. An update transaction that follows the principles of atomicity, consistency, isolation, and durability. A failover configuration in which a service running on an active node has an available passive node ready to start and take over in case the active node fails. StarTeam supports active/passive clustering. A persistent, stored, and versioned object. It is the most important business object of VCS and SCM systems. An item property that controls whether or not the referenced artifact will be branched if an update is made to the artifact through the item. The set of all revision branches for a given artifact. New artifacts start with a main branch with the first revision having version number 0 and dot notation 1.0. An artifact that represents a defect, an enhancement request, or another reason for a software change. The most recent artifact revision that is common to two artifacts residing in the same branch tree. The common ancestor is used in three-way merge operations. An instance of a StarTeam deployment. Each StarTeam configuration has its own database and vault. At least one project must be added to a configuration before it can be used to hold artifacts.
ACID transaction active/passive clustering artifact branch-on-change (BOC) branch tree
change request common ancestor revision (or just common ancestor) configuration
configuration timestamp An item property that controls what version of an artifact is referenced. If the configuration timestamp is unused, the item floats to the tip revision of the artifact. Otherwise, it points to revision that was tip as of a specific timestamp. continuous integration A software development practice that emphasizes frequent builds and testing. The goal of continuous integration is to encourage the stability of a development streams current (tip) configuration. A dotted decimal notation assigned to artifact revisions to indicate both the branch on which the revision resides and the relative version number of the revision within the branch (e.g., 1.4 or 1.2.1.5). An item write lock that can only be held by one user. An exclusive lock notifies other users that the lock owner is potentially modifying the locked item. Compare to shared lock.
dot notation
exclusive lock
Borland Software
Page 88 of 90
StarTeam Best Practices file floating An artifact that stores properties and content, thereby representing the data held by a disk file. For items and links, a reference that always points to the current (tip) revision of an artifact is considered floating. In contrast, a reference can be pinned to a specific revision. An artifact that represents a disk directory, thereby able to hold other artifacts. In StarTeam, a folder can hold any type of artifact: files, change requests, tasks, etc. An association object that connects an artifact to a specific view. In addition to exposing artifacts to views, items facility containment hierarchies and paths, control artifact update behavior, and define share trees. A named tag that identifies a related set of artifact revisions. In StarTeam, a view label typically identifies a snapshot of an entire view, whereas a revision label identifies a small subset of revisions related to a particular purpose. A connection object that relates two artifacts. Each endpoint of a link can float to the current revision of the artifact branch to which it points or be pinned to a specific revision on that branch. The initial branch created for a new artifact. This branch always has dot notation 1.x; the first revision on the main branch is always 1.0. For items and links, a reference that is configured to point to a specific revision is considered pinned. In contrast, a reference can be floating to the current (tip) revision. In VCM, a merge operation that propagates changes from a child view to its immediate parent view. In VCM, a merge operation that propagates changes from a parent view to one of its immediate child views. In VCM, a merge operation that propagates changes from one view to some other view that belongs to the same project. A centrally-located store for artifacts. With StarTeam, the repository is a database that holds all metadata and data except for file content, which is stored in the vault. An artifact that represents a business need. Requirements are early lifecycle artifacts that guide the design, construction, and testing of software components. A stream of artifact revisions that are considered linear, sequential changes. At any given revision, some artifact types can be branched to form a new revision branch. A comment specific to an artifact revision. Compared to other properties, which keep the same value in all revisions until explicitly changed, the revision comment is not carried forward to new revisions and must be set for each change. Page 89 of 90
folder
item (or view member)
label
link
main branch pinned
promote rebase replicate repository
requirement revision branch (or just branch) revision comment
Borland Software
StarTeam Best Practices revision control revision tree security principal shared lock (or nonexclusive lock) software configuration management (SCM) source revision target revision task three-way merge Synonym for version control. Synonym for branch tree. A user or group for the purposes of defining security. An item read lock that can be held by multiple users. Compare to exclusive lock. The process of managing changes to the artifacts in a software development process. In a three-way merge, the artifact revision containing changes to be merged to the target revision. In a three-way merge, the artifact revision that will be updated with changes contained in the source revision. An artifact that represents a needed, active, or complete unit of work. StarTeam tasks are analogous to tasks in project management systems. An artifact merge operation in which changes in a source revision are propagated to a target revision. A three-way merge operation considers the common ancestor revision to determine what changes to propagate. The current (most recently created) revision of an artifact. In a rolled-back view (snapshot), the tip revision is the most recent revision available in the snapshot. An artifact that represents a newsgroup-like message. Topics form conversation threads that increase the collaboration features of a project. The process of maintaining an accurate history of artifact revisions. A software application that provides version control features. A unique number assigned to a specific artifact revision. The first revision of an artifact is usually 0 or 1. Each new revision after that is assigned a version number incremented by 1. A new change management facility introduced in the StarTeam 2006 release. VCM propagates changes a source view to a target view with three types of merge operations: rebase, promote, and replicate. A record indicating the completion of work on behalf of a specific task. A set of folders on a client workstation that are used for file check-in and checkout operations for a specific StarTeam view.
tip revision topic version control version control system (VCS) version number (or just version) view compare/merge (VCM) work record working folders
Borland Software
Page 90 of 90

StarTeam 2008 Best Practices

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

StarTeam 2008 Best Practices

Uploaded by

Copyright:

Available Formats

StarTeam Best Practices

Getting the most from StarTeam

Randy Guck Chief Scientist, StarTeam Borland Software May, 2008

StarTeam Best Practices

StarTeam Best Practices

StarTeam Best Practices

StarTeam Best Practices

Figure 1: Version numbering

Amazingly, some VCS systems have no container other than an instance!

New branch created from main branch version 1

Revision 3 on the lowest branch merged to both upper branches

New branch created from main branch revision 2

Figure 2: Branching and Merging

StarTeam Best Practices

Vault StarTeam Server process

Command StarTeam Line SDK Interface

Custom StarTeam ApplicaSDK tion

Figure 3: Overview of the StarTeam Architecture

StarTeam Best Practices

Database StarTeam Server process Vault

MPX Message Broker

Figure 4: Role of the MPX Message Broker.

StarTeam Best Practices

StarTeam Server process Vault

broker-tobroker forwarding file checkouts

Root Message Broker

Root Cache Agent

Remote Cache Agent

Remote Message Broker

Figure 5: MPX Cache Agents

StarTeam Best Practices

Server Configuration Prod1

BedRock SP1.0 (grandchild view)

BR SP1 HotFixes (great-grandchild view)

Figure 6: StarTeam Containers

StarTeam Best Practices

StarTeam Best Practices

First branch created from revision 1.2

Second branch created from revision 1.2

New branch created from revision 1.2.2.1

Figure 7: Branching and Dot Notation

StarTeam Best Practices

Figure 8: Merging Between Branches

StarTeam Best Practices

Revision 1.x branch (OID = Root OID)

All revisions for file foo.java Root OID=123

Revision 1.1.1.x branch (OID Root OID)

Revision 1.1.1.2.1.x branch (OID Root OID)

OID=400 Version=0 (1.0)

All revisions for CR 413 Root OID=400

Figure 9: Artifact OIDs and Root OIDs

StarTeam Best Practices

Figure 10: Connecting and Organizing Artifacts with Items

StarTeam Best Practices

Link endpoint endpoint Link endpoint endpoint

File bar.java Version=0 (1.0)

Task 1123 Version=0 (1.0) Version=1 (1.1) Version=2 (1.2)

File baz.java Version=0 (1.0) Version=1 (1.1)

Figure 11: Example Process Items with Links

Example view and revision labels are shown in Figure 12.

StarTeam Best Practices

View label Build 9.0.123

Revision label CR 413 Mods