StarTeam 2008 Best Practices

StarTeam Best Practices Getting the most from StarTeam

Randy Guck Chief Scientist, StarTeam Borland Software

May, 2008

StarTeam Best Practices

Borland Software Page 2 of 90

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



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



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



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.

1 ACID properties are the yardstick of database transactions: atomicity, consistency, isolation, and durability.



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,

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



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.



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

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

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



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 zero-based version sequence.

File: foo.java0 1 2 3 4

Version numbers

Initial revision(file added)

Update revisions(file modified)

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. Non-text 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



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 well-defined 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,

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



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, third-party 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



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.

0 1 2 3 4

0 1 2 3

0 1 2 3

Main branch

New branch created frommain branch version 1

New branch created frommain branch revision 2

4

Revision 3 on thelowest branch mergedto both upper branches

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.

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



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.



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

8 Confusingly enough, such a development stream is sometimes called a branch, not to be confused with the version branches of

individual artifacts.



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 labor-intensive 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.



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?



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 geographic- or 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.



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.



3.2. Standard Architecture Overview

The core components of StarTeam architecture are depicted in Figure 3.

StarTeamServerprocess

CommandLine

Interface

ServerAdminis-

trator

CustomApplica-

tion

Cross-Platform

Client

StarTeam ServerStarTeam ServerStarTeam ClientsStarTeam Clients

Vault

NetworkNetwork

FilesHive 1

FilesHive 2StarTeam

SDK

StarTeamSDK

StarTeamSDK

StarTeamSDK

LAN, WAN,VPN, etc.

TCP/IP

command API

Database

Figure 3: Overview of the StarTeam Architecture

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.



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.

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



StarTeamServerprocess

Client

Client

Client

Vault

MPXMessageBroker

Client

command API

update events

event API

Database

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.



StarTeamServer

process

Client

Client

Client

Vault

RootMessage

Broker

Client

RemoteMessageBroker

RemoteCacheAgent

RootCacheAgent

to local clients

Remote siteRemote site

command API

broker-to-broker forwarding

updateevents

filecheck-outs

updateevents

filecheck-outs

Server siteServer site

Database

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.



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.



Server Configuration Prod1

Project BedRock

BedRock (main view)

BedRock 1.0(child view)

Pegasus(child view)

Project AppSuite

AppSuite (main view)

Public Docs(grandchild view)

BedRock SP1.0(grandchild view)

Sources(child view)

Bobs Sandbox(grandchild view)

Team1 Sandbox(grandchild view)

Jeans Sandbox(grandchild view)

BR SP1 HotFixes(great-grandchild view)

DocWork(child 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.



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.



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.



0 1 2 3 4

1.0 1.1 1.2 1.3 1.4

0 1 2 3

1.2.1.0 1.2.1.1 1.2.1.2 1.2.1.3

0 1 2 3

1.2.2.0 1.2.2.1 1.2.2.2 1.2.2.3

0 1

1.2.2.1.1.0 1.2.2.1.1.1 1.2.2.1.1.2

2

version numbers

dot notation

Main branch

First branch createdfrom revision 1.2

Second branch createdfrom revision 1.2

New branch createdfrom revision 1.2.2.1

4

1.2.2.4

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.



1.3 1.4

1.2.1.2 1.2.1.3

source branch

target branch

merge

1.2.1.4

Source revision 1.4 is merged totarget revision 1.2.1.3. Source revision

1.2 is the common ancestor. New targetrevision 1.2.1.4 is created by the merge.

MP

1.2

1.2.1.0 1.2.1.1

sourcecommonancestor

target result

A merge point is stored indicatingthat source revision 1.4 is resolved

with target revision 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.



Version=2 (1.2)

Version=1 (1.1)

OID=123

Version=0 (1.0)

Version=2 (1.1.1.2)

Version=1 (1.1.1.1)

OID=311

Version=0 (1.1.1.0)

Version=2 (1.1.1.2.1.2)

Version=1 (1.1.1.2.1.1)

OID=875

Version=0 (1.1.1.2.1.0)

Version=2 (1.2)

Version=1 (1.1)

OID=400

Version=0 (1.0)

Version=2 (1.2.1.2)

Version=1 (1.2.1.1)

OID=573

Version=0 (1.2.1.0)

All revisionsfor file foo.javaRoot OID=123

All revisionsfor CR 413

Root OID=400

Revision 1.x branch(OID = Root OID)

Revision 1.1.1.x branch(OID Root OID)

Revision 1.1.1.2.1.x branch(OID Root OID)

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.



Item

Item

Item

Item

Item

Filea.txt

Fileb.java

Filec.jar

Viewroot

parent

Item

Item

shared file

Filed.doc

Folderfoo

Folderbar

/foo/a.txt

/foo

/foo/b.java

/foo/c.jar

/foo/bar

/foo/bar/c.jar

/foo/bar/d.doc

artifact

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("") where 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.

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



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.



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.

14 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

StarTeam 2008 Best Practices

Documents

Transcript of StarTeam 2008 Best Practices