Guidelines for configuring StarTeam repositories. A Borland White Paper By the Development Resources Platform Team December, 2003
Contents Overview.............................................................................3 A Quick Tour of StarTeam Essentials.....................................................4 Containers.........................................................................4 Objects...........................................................................5 Objects Versus Items................................................................6 Lifecycle Features...................................................................8 Server Configuration Principles..........................................................9 Consider Business Unit Divisions......................................................9 Leverage StarTeam s Support for Distributed Teams.......................................9 Don t Partition for Internal/External Access..............................................9 Avoid Servers That Get Too Big......................................................10 Share Machines When Practical.......................................................10 Split-up Large Servers..............................................................11 Project Configuration Guidelines........................................................12 Keep Projects Autonomous..........................................................12 Example 1: A Simple Client/Server Application......................................13 Example 2: An Independent Client Module..........................................13 Example 3: A Complex Financial Application Suite...................................13 Handle Cross-Project File Dependencies................................................14 Support Cross-Project Activities......................................................15 View Configuration Practices...........................................................16 Understand View Types.............................................................16 Do s and Don ts of Views...........................................................17 DO Treat Views As Streams....................................................17 DO Use The Main View as the Main Baseline........................................18 DO Use Branch-All Views.......................................................18 DO Use View Labels and Promotion States..........................................18 DON T Go Beyond 2 or 3 View Levels.............................................18 DON T Use Some View Types....................................................18 DON T Use Too Many Views....................................................18 Use Views to Support Iterative Development Scenarios....................................19 Scenario 1: Small Development Teams.............................................19 Scenario 2: Large Development Teams.............................................20 Scenario 3: Concurrent Development Activities.......................................21 Other Tips and Techniques.............................................................23 Achieve Consistent Check-in and Check-out.............................................23 Simplify Merge Down with Branch-All Views.........................................23 Know What Operations Are Expensive.................................................24 Establish a Quick Backup Procedure...................................................25 Use Merge Points Wisely............................................................25 Use a Test Server..................................................................26 Glossary............................................................................27 2
1 Overview This article provides best practices guidelines for configuring and using StarTeam repositories. Best practices means that the tips and techniques provided here have been successfully used by many StarTeam users. Since StarTeam is a highly flexible software configuration management (SCM) system, there are many ways to support specific application lifecycle management (ALM) practices. Some approaches are better than others based on experience and on going with the grain of StarTeam features. The intent of this article is to highlight those approaches. This article focuses on configuration practices, which includes the creation and organization of StarTeam repositories, projects, and views. It encompasses the techniques by which these configuration features can be effectively used to support iterative development lifecycles, including concurrent development. Example scenarios are provided to illustrate how to configure StarTeam to support them. The guidelines provided here are intended for StarTeam administrators, project managers, and developers who will advise or manage the organization of StarTeam repositories. The operative word here is guidelines you should follow these suggestions to the degree that they match your organization s need. Since there are countless variations of development approaches, you should expect to tailor the proposals provided here for your requirements. The information in this article is relevant to the StarTeam 5.3 release. Be sure to consult other documentation such as the StarTeam Getting Started Guide, StarTeam User s Guide, and StarTeam Administrator s Guide. Also, see the article StarTeam Performance and Scalability Techniques for information on hardware options, capacity planning, and performance tuning for StarTeam deployments. 3
A Quick Tour of StarTeam Essentials 2 A Quick Tour of StarTeam Essentials To use this guide, you should be familiar with basic StarTeam concepts and features. This section reviews key StarTeam features and explains how terms such as items and objects are used in the remainder of this guide. 2.1 Containers The most basic StarTeam concepts are containers that hold information objects and/or other containers. These include StarTeam server configurations, projects, and views:! A server configuration is a single deployment instance of StarTeam. All files, change requests, and other artifacts that can be interrelated and managed as a whole reside within a single server configuration. Except for file content, all data and metadata for a server configuration are stored in a database termed the repository. File contents are managed in operating system-level files collectively known as the vault. Vault information is divided into separate areas for storing archive, cache, and attachment files. Suggestions for deciding when to create a new server configuration are discussed in section Server Configuration Principles.! Within a server configuration, artifacts are organized into projects. Before a server configuration can be used, at least one project must be created to hold files and other objects. A server configuration can hold multiple projects, each oriented to the lifecycle needs of a specific team, application, or component. Guidelines for when you should create a new project and what it should contain are discussed in section Project Configuration Guidelines.! Each StarTeam project can possess one of more views. Every project automatically receives a main view through which folders, files, and other objects can be organized. Additional child views can be created to represent subsets of the main project information, historic snapshots of project information, or work areas for new development work. StarTeam provides a wide range of options for view creation to support a wide range of development scenarios. Considerations for how you should use views are provided in section View Configuration Practices. An example StarTeam server configuration is shown in Figure 1 Example StarTeam Server Configuration. In this example, the server configuration contains two projects: Dev1, whose main view has two child views, and Doc1, whose main view has a single child view, which in turn has a third-level (grandchild) view. As shown, the development artifacts of all projects and views for the server configuration are stored in a single repository and vault. 4
A Quick Tour of StarTeam Essentials Server Configuration Dev1 (project) Dev1 (main view) Doc1 (project) Doc1 (main view) Release 1.0 (child view) Pegasus (child view) DocWork (child view) Public Docs (grandchild view) Archive Cache Attachments Database Repository Vault Figure 1 Example StarTeam Server Configuration Through the remainder of this article, a server configuration is often referred to as simply a server. This is because each server configuration is often deployed on its own server machine, managed by its own StarTeam server process. However, be aware that StarTeam allows multiple server configurations and server processes on a single machine, hence the server configuration-to-machine relationship doesn t have to be one-to-one. 2.2 Objects Objects are the core information artifacts within a server. Objects, also known as content objects, are versioned so that individual revisions can be accessed, labeled, branched, and so forth. The content of an object is stored as a series of properties, each of which has a name and a value. For each object type, you can add custom properties if you need to store more information than is available via the built-in properties. StarTeam supports the following object types: Files: As with all SCM systems, files are the most important artifact in StarTeam. File properties contain metadata such as the Modified By property, security, and history, all of which is stored in the repository. Files also contain binary or textual data, which is stored in the vault. Files are versioned and can be branched into separate version trees. Files are supported by other configuration and management features such as links and labels. Change Requests (CRs): StarTeam supports integrated defect and enhancement request tracking via change requests. Like files, CRs can be versioned and branched, linked, labeled and so forth. CRs are typically used to represent discrete requests such as bug reports or new feature suggestions. Tasks: StarTeam tasks are analogous to work items found in project management systems such as Microsoft Project. (In fact, StarTeam tasks can be synchronized with MS Project tasks.) A task typically represents a step in a larger work plan and may be assigned to multiple people. Hence, a 5
A Quick Tour of StarTeam Essentials task may be divided into subtasks and tracked via multiple work records. Tasks are versioned and can be labeled, linked, and so forth, however they do not branch like files and CRs. Topics: A topic is a newsgroup-like message that can be posted by one user, responded to by another, and so forth. A chain of topics on a given subject create a threaded discussion that can be attached to a file, CR, or other object to capture a conversation important to a development activity. Like tasks, topics are versioned but do not branch. Requirements: StarTeam supports lightweight requirements objects that can be used to document early development lifecycle steps. Requirements can be authored and utilized directly in StarTeam, or they may be imported and synchronized with objects from formal requirements management systems such as CaliberRM. Requirement objects support versioning, linking, and labeling but do not branch. Folders: Every view has a root folder, which typically contains a tree of subfolders beneath it. A folder can contain objects of any type, including other folders. Although folders are containers, they have properties and are versioned, hence they are also objects and, like files and CRs, can branch. Note that a folder s logical path name is defined by prefixing its name with that of its parent folders names. However, the corresponding working folder path, which is where files within the folder are stored locally at the client, may not match the logical path name the working folder path can be overridden on a per-folder and per-client basis. Because objects are exposed via items, the terms object and item are sometimes used interchangeably. However, objects and items are distinct entities, whose differences are discussed next. 2.3 Objects Versus Items It is important to understand how objects are surfaced through views. Every content object is exposed to a view via an association object called an item (also called a view member). When a new object, say a file, is added to a view, StarTeam creates a new file object with version 1.0, and it creates a new item that points to that file. The item not only specifies which file is referenced, but it specifies the folder in which the file appears. So, for example, if you move the file from one folder to another, you actually modify the file item to point to a different parent folder item, but the file and folder objects are not actually modified. The relationship between items and objects is illustrated in Figure 2 Items Versus Objects. In this example, two views are shown, each of which points to its root folder item. Every item points to a corresponding object, which holds the object properties, and every item other than the root folder item points to a parent folder item, which designates the folder in which it resides. 6
A Quick Tour of StarTeam Essentials Items Objects View 1 root folder Folder File parent folder File CR Folder Task File Folder parent item File shared object Req. View 2 root folder child item share parent Folder File Figure 2 Items Versus Objects An item created on behalf of a new object is called a parent item. A child item is created by copying a parent or child item, allowing the same object to be surfaced in another location. A child item points to the parent item from which it was copied. Child items are created in two situations:! Child views: When a new view is created as a child of another view, the parent view s items are copied to create the child view s items. The objects themselves are not copied the new child view items merely point to the same objects.! Shares: An item can be explicitly copied, creating a share item. This is done, for example, by holding the Ctrl key and dragging an item from one folder to another in the StarTeam client. In this case, the selected item is copied, initially pointing to the same object as the original item. The primary difference between child view items and child share items is their initial configuration. The behavior of an object is partly influenced by the configuration of the parent or child item through which it is manipulated. To understand how parent and child items behave, it is necessary to understand the separation between object and item properties: Object properties: Most of the properties you see name, modified by, version, data (for a file), etc. belong to the object. When the object is modified in any way, another revision of the object is created. For example, if the current revision of a CR is 1.2 and the Responsibility property is modified, the modified CR is stored as revision 1.3. If a new version of a file currently at revision 1.4.1.2 is checked in, the new version is 1.4.1.3. Item properties: An item contains properties that define which object is referenced, the folder in which it should appear, and how updates to the object via the item should be handled. Most of an item s properties such as parent view and parent folder are implicitly managed by StarTeam based on client actions. There are three key item properties that affect the manipulation of the object referenced by the item: 7
A Quick Tour of StarTeam Essentials! Object ID: This property defines the object branch to which the item refers. Each new object receives a unique object ID, and its revision number begins at 1.0. The object s revision number is incremented each time it is updated (1.1, 1.2, etc.), but the object ID is not changed. Hence, the object ID referenced by an item points to the entire object branch and possibly a specific revision. When an object branches, a new object with a new object ID is created, and its revision number is extended to reflect the branch point (e.g., 1.2.1.0). An item refers to the new branch by updating the object ID to which it points.! Behavior Configuration: This property defines whether or not the item is floating or pinned to a specific point in time. When an item s behavior is set to floating, the item points to the tip revision of the object branch to which the item refers. When the behavior is set to a specific point in time, the item refers to the object revision that was current at that time.! Branch-on-change: This property is only valid for a child item referencing a file or CR. It controls what happens if the object is modified via the item. If true, branch-on-change causes a modification to start a new branch for the object. For example, a file checked in via the item when the current revision is 1.2 will start branch 1.2.1.0. When branch-on-change is false, either the underlying object has already branched via this item, or updates via the item operate on the same object as the parent item, or the item is read-only (frozen). Child view items are automatic shares that are created and managed by manipulating the views to which they belong. Hence, you can usually focus on managing the view itself without worrying about the child items. However, manual shares that you create via UI gestures or SDK commands require more attention to item properties to understand how updates will propagate to other items in the same share tree. For example, shared item operation can be complicated when a parent item is deleted, an intermediate shared item s behavior is changed, or the shared item is a folder. For these reasons, shares should be used cautiously. Furthermore, as will be discussed later in section Project Configuration Guidelines, shares across project boundaries should be used with even greater scrutiny. 2.4 Lifecycle Features By themselves, containers, objects, and items allow you to capture development artifacts and organize them according to the needs of your projects and teams. StarTeam provides additional core features that support processes such as builds, releases, and change management. These features focus on the development lifecycles through which information flows: Links: StarTeam links allow arbitrary objects to be related. For example, a defect CR can be linked with the files modified to fix a defect. The link end-point objects can be pinned to a specific revision of an object, or they can float to the latest version of the object. Labels: A specific set of object revisions can be referenced via a label. A view label typically references a specific revision of all objects in a view, while a revision label typically references specific versions of a small group of objects. StarTeam promotion states are built on top of view labels and support the notion iterative build, release, and deployment processes. Process Rules: A project can be configured to enforce process rules, which require the use of specific CRs, tasks, or requirements as controlling items for file check-ins. When activated, process rules promote change traceability by linking new and modified files to the process items to which they are related. 8
Server Configuration Principles 3 Server Configuration Principles This section provides some guidelines you should consider when deciding how many StarTeam server configurations to deploy. This section does not focus on performance and scalability considerations since these factors are covered more extensively in other articles. Use these guidelines to help answer the question When is the right time to deploy a new StarTeam server? Since each server has its own database instance and vault, multiple servers increase administrative costs. On the other hand, distributing your organization s StarTeam projects among multiple servers increases project independence and improves performance and availability factors. Below are some strategies to consider when developing your organization s server deployment plan. 3.1 Consider Business Unit Divisions When multiple business units require their own StarTeam projects, it often works well to define StarTeam servers along organizational boundaries. That is, deploy a separate StarTeam server for each major business unit or department, allowing each to access its own projects. Dividing along business unit lines isolates separate (and sometimes competing) requirements for security, backup processes, and other administrative issues. Separate servers can also help mitigate ownership or turf issues. Where development lifecycle processes cross configurations, clients can open multiple projects in a single StarTeam client. Deploying interrelated artifacts from one project to another can also be used to address cross-configuration integration needs. This subject is discussed further in section Project Configuration Guidelines. 3.2 Leverage StarTeam s Support for Distributed Teams In general, team members that require access to the same development artifacts should share a single StarTeam server. Dividing or replicating a StarTeam server solely due to geographically dispersed teams is usually not necessary. StarTeam was designed to work well over the Internet, even over slow connections. Remote developers often find that performance is adequate over long distances. Using StarTeamMPX and deploying MPX Message Brokers to regional development centers increases responsiveness even further. 3.3 Don t Partition for Internal/External Access In many situations, teams both behind and outside of the corporate firewall require access to a single StarTeam server. A common practice in this scenario is to deploy the StarTeam server in the DMZ area of the firewall, placing the database on a separate server behind the firewall. Depending on the capabilities of the firewall, it may be appropriate to configure a dedicated port to the StarTeam server. Alternatively, you can install two network interface cards (NICs) on the StarTeam server machine: one outward facing and one inward facing. In this scenario, StarTeam allows specific inbound IP addresses (or address ranges) to be configured with different connection security requirements. Other security features such as strong password management and automatic account lockouts further increase the viability of using the same StarTeam repository for both internal and external developers. 9
Server Configuration Principles 3.4 Avoid Servers That Get Too Big As with all client/server applications, the demands on the StarTeam server grow as the number of artifacts and the number of concurrent users grow. Even with high-end hardware, the server s CPU, memory, disk, and network resources are finite, and each could become a bottleneck to server responsiveness. (Even though it s usually easy to add more disk, disk contention is still a potential bottleneck in large servers.) Although there are no hard numbers that define when a server is too big, below are some numbers based on experience that suggest boundaries of what constitutes too big : total # of: No problem Getting big Probably too many Projects 50 200 500 Views 100 400 1000 Items (all types; tips) 1,000,000 4,000,000 10,000,000 Files (tips) 500,000 2,000,000 5,000,000 Registered Users 500 1,000 2,000 Concurrent Users 100 250 1000 Your mileage will vary from these numbers depending on hardware and usage patterns. One StarTeam customer, for example, has been able to run with 3,000 registered users and 400-600 concurrent users. 3.5 Share Machines When Practical If your organization needs to support multiple, smaller server configurations (10-20 concurrent users each), they can be placed on the same machine. Some important points to consider in this scenario are:! Each server configuration must be supported by a separate StarTeam server process.! Two processes running on the same machine must accept inbound connections on different port numbers. (This is a TCP/IP restriction.)! Each server configuration can be independently marked to have its StarTeam server process start as a service.! Each server configuration must have its own database and vault, but the databases can be shared in the same partition. For medium size server configurations (up to 50 concurrent users), the StarTeam server process, database, and vault can all reside on the same machine. As the total number of artifacts and/or concurrent user count rises, you ll want to separate the database onto its own machine first, connected to the StarTeam server via a high-speed (100Mbit or 1Gbit) network connection. If your organization needs to support multiple, large StarTeam servers, you can still deploy the databases on a shared machine with multiple CPUs and lots of memory, connected to the StarTeam server machines with a high-speed network (1Gbit). The vaults can also be shared on a high-speed storage device, provided it supports high concurrency (e.g., multiple controllers and/or RAID 5). In short, you don t have to dedicate a machine to each StarTeam server process, database, and vault, even for large installations, provided that you plan for high concurrency. See the article StarTeam Performance and Scalability Techniques for more information on hardware options, capacity planning, and performance tuning. 10
Server Configuration Principles 3.6 Split-up Large Servers Splitting-up an overly large server is possible, but it is not trivial. The basic process for moving a set of projects from one server to a new one is as follows: 1. Perform a full dump (DB + archive) of the server configuration to be split. 2. Restore the database and archive on a secondary system. 3. Change the server GUID on the secondary system (ask Borland support for the process to do this). 4. Delete the unwanted projects on the secondary system. 5. Run the StarTeam purge utility on the secondary system to clean-up deleted database records and vault files. 6. Verify the secondary system via vault-verify, testing, etc. 7. Deleted the original (now cloned ) project(s) from the original server. 8. Run the purge utility on the original server to return database and archive space. Depending on the size of the server configuration, this process can take many hours, so plan to do it over a weekend or other down time. The degree to which you succeed with this process depends largely on the autonomy of the projects that you move. Shares between the moved and unmoved projects will reduce the amount of 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. 11
Project Configuration Guidelines 4 Project Configuration Guidelines As with servers, when to create and how to organize StarTeam projects is an essential decision. The number of projects in a server and the number of artifacts managed in each affects issues ranging from performance to ease of administration. Here are some guidelines for deciding how to set-up your projects. 4.1 Keep Projects 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, as well as construction phase artifacts such as source files.! A project should include artifacts authored in lifecycle phases, and non-authored artifacts required to perform authoring. This includes, for example, all files authored by the IDEs such as workspace/project files, source code, and resource files. It also includes input files such as.h,.lib,.jar, or.dll files that are authored or generated elsewhere but required by the project s IDEs or build processes. Input files may originate from third parties or from other projects in the same or other StarTeam configurations. (Transferring artifacts from one project to another is discussed further later.)! Files directly generated from authored files such as.obj,.class, and.lib files generally do not need to be checked into the project. However, it is common practice to check-in final binaries such as.jar,.war, and.exe files that are delivered to other projects, engineering test, QA, or other deployment phases. The need to place generated files under version control is highly dependent on your own development, testing, and release methodologies.! A project should have a long-term view of the products or components it supports. That is, it should house all artifacts generated over multiple iterations through the lifecycle. This means that the project supports multiple versions of its applications or components, representing the complete history of those modules. How views are used to support specific lifecycle activities and releases is discussed in section View Configuration Practices.! StarTeam works best when the supplemental objects (CRs, tasks, topics, and requirements) related to a project s files are stored in the same project. This allows, for example, a CR to be entered, tracked, and linked to the files in the same project to which the CR is related. This approach requires some special considerations for activities such as CR triaging and crossproject reporting. These issues are discussed later. 12
Project Configuration Guidelines Some customers have attempted to use projects to separate development phases (e.g., design and development) or development artifact types (e.g., files and CRs). The artifacts are then interrelated by sometimes heavy use of links or shares. However, experience has found that copious use of shares especially cross-project shares results in difficulties in version control, reporting, security, and even performance. Evidence suggests that artifacts that are related to the same applications and components, though of different types and/or lifecycle relevance, are more effectively managed in the same project. 4.1.1 Example 1: A Simple Client/Server Application Scenario: A commercial software application consists of a server written in C++ and a single client, also written in C++. Furthermore, the client and server modules share a fair amount of source code and IDE projects that generate common DLLs. The client and server modules are generally enhanced and released together. In this scenario, a single StarTeam project should be used to manage the combined files of both the client and server modules. The sharing of source code and shared release schedules suggest that the modules are cohesive parts of a single application. Requirements, design documents, CRs, and other objects required for all lifecycle phases of the client and server modules should be managed in the same project. 4.1.2 Example 2: An Independent Client Module Scenario: A new Java client application is developed that uses the same server described in Example 1. Building and compiling the Java client requires some of the header files and one of the DLLs used by the server to produce a JNI wrapper, but no other source files. Furthermore, the Java application accesses other third-party servers and is generally enhanced and released on independent schedules from those used by the client/server modules. In this scenario, it is reasonable to use a separate StarTeam project to manage the Java client s artifacts. The latest header files and generated DLL needed by the Java client are checked into a external components folder by the build process used in the client/server project. All CRs, tasks, and other lifecycle objects related to the Java client are managed in the same project. 4.1.3 Example 3: A Complex Financial Application Suite Scenario: A complex application suite consists of a set of foundation components and nearly 100 separate applications, divided into five functional areas: accounting, insurance, forecasting, etc. The applications are developed by different teams and all use the foundation components, which are jointly maintained by the development teams. Applications within a functional area are highly interrelated, but applications between functional areas are fairly independent. The foundation component library is enhanced and released on its own schedule, but the entire application suite is released as a commercial product in coordinated releases. Although the entire application suite is interrelated, multiple projects should be used due to the overall application suite size. The foundation components are managed in one project, and each of the five functional areas utilize a separate project to manage the corresponding applications (six projects total). The foundation project is enhanced, built, and then deployed to each of the functional area projects by checking in generated jar files. Each development team generally opens only one project to perform their normal work. However, a special build script (using the StarTeam SDK) is used to extract files from multiple projects and generate whole suite builds. The build script also automates the management of common view labels and promotion states across projects. 13
Project Configuration Guidelines 4.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 share s behavior is configured to floating, changes from the parent project flow into the child project immediately, sometimes at inconvenient times. Many StarTeam users find that they need to manage the update propagation on a more scheduled basis.! If a share s behavior is configured to a specific timestamp, it must be occasionally adjusted to allow updates to propagate. This makes the shared item read-only, and continually adjusting the configuration timestamp for a large number of shares can become burdensome.! If a share s branch-on-change property is set to true (perhaps accidentally), and a change is made to the child share, the object will branch in the child project. This severs the share from the parent object and is difficult to reverse. If the child share is a folder, an innocuous change such as modifying the working folder will cause the folder object to branch.! When an update is made to an item that participates in a share tree, every item in the tree must be locked. As the share tree grows, update performance is impacted proportionately.! Normally, when obsolete views and projects are deleted, the StarTeam purge utility can be used to return unused database records and archive files. However, shares used by a deleted project or view can prevent the purge utility from achieving the expected reduction in database and archive size. In short, it might not be possible to reduce the size of servers that use cross-product sharing. Because of these reasons, other techniques have proven to be more effective at handling cross-project file dependencies. Below are some alternatives to sharing that work in different situations:! Deployment approach: If a project owns a set of files that must be checked into other projects, you can establish a process in which the files are periodically deployed. This means that the file set is checked into the target project(s) on an as-needed basis, perhaps by a script. Often, a build script is a good place to embed the deployment task, especially if the file(s) to be deployed are generated by the build.! Configuration approach: Sometimes the codependent files don t need to be checked into each project, but they need to participate in a common process such as a build or delivery process. In these cases, a simple XML file can be constructed that defines the files that participate in process. If the file is checked into an established location and updated when the configuration changes, then build, release, or other scripts can check-out the XML file, parse it, and base their processing on its instructions.! Link approach: In lieu of shares, links can be used to connect objects across servers. Links do not possess many of the problems exhibited by shares, and they can be pinned, unpinned, and moved to refer to different object revisions. The downside of using links is that they are untyped, not versioned, and possess no properties other than a link comment to distinguish them from other links that may be present. In the end, shares still may be the most appropriate way to expose files from one project to another, but the above approaches should be considered first. 14
Project Configuration Guidelines 4.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:! Multi-project builds: Build procedures that require files from multiple projects can use the StarTeam SDK, which can open multiple projects at the same time. Alternatively, iterative calls to the StarTeam command line tool (stcmd) can be used to check-out files from each of the required projects.! Defect triaging: When a new defect is discovered, it is often entered as a CR before the module that must be repaired is known. This means that, if CRs are normally managed in the project containing the files that will be modified, a paradox exists in determining where to create the CR in the first place. A project leader or other person usually triages the CR by assigning it to whoever he or she thinks should handle it. As the CR is analyzed and addressed, the module that is ultimately modified to address it may not be known for a while. A simple solution for this scenario is to place all CRs in a well known place (perhaps a new defects project) and move (not copy) them to the appropriate project as needed.! Cross-project reporting: Currently, StarTeam does not provide built-in, cross-project reports. Consequently, if you want to generate reports such as all open CRs across all projects or cross-server file metrics, your best option is to use the StarTeam SDK to write simple reporting apps in Java, VB, or your favorite language of choice. 15
View Configuration Practices 5 View Configuration Practices Views are one of the most important configuration concepts in StarTeam. They represent portals into project artifacts that can serve a wide range of development process activities. Views can be likened to a Swiss army knife that offers many tools and options to suit a wide range of needs, but you have to be careful a couple of the blades can really cut you! In this section, the basic view types and their general characteristics are discussed. Also provided are some basic view do s and don ts and suggestions on how views can be used to address various development lifecycle scenarios. 5.1 Understand View Types There are many types of views whose functionality varies based on the options used to create them. Some view types are useful for specific situations; some views are rarely useful. Since view behavior is based on the options used to create them, view types are not formally defined, which can make them a little confusing. Below is one way to break-down view types and describe their general functionality:! Non-derived view: This is also called a blank view. It is not derived from any existing views, rather it starts out empty. If only new folders, files, and other objects are added to it, it effectively acts like a project except that, as a view, it still belongs to the project from which it was created. If objects that originate elsewhere are shared into a non-derived view, it acts like an arbitrary assembly of objects. The shared items can float and therefore updated, or they can be fixed and therefore read-only. Non-derived views are rarely used.! Derived view: A derived view is created with some other view as the perspective. One of the perspective view s folders is chosen as the root of the derived view, hence the derived view is a window into the objects at which it is rooted. However, a derived view has many different behaviors and uses depending on other options:! Reference view: A reference view is a derived view that is a pure subset of the objects that are exposed through it. That is, the parent and reference view refer to the exact same objects, so changes though one affect the other view. Items in a reference view do not branch, hence reference views are also called non-branching views. The reference view utilizes the same view labels as its parent. Reference views can be further divided into two types: " Updateable reference view: The items in an updateable reference view float to the tip revision of corresponding objects, hence the objects can be updated via the reference view. These changes appear immediately in the parent view as well. In practice, updateable reference views are rarely used. They can be confusing since updates to the reference view flow through to the parent view and vice versa. The sub-setting ability of the reference view may be useful in some cases, but similar functionality can be accomplished with security settings. " Read-only reference view: The items in a read-only reference view are read-only and hence can t be modified via the view. Some or all of the view s items configuration may be floating, allowing changes from the (updateable) parent view to show through. Conversely, items can be pinned to a specific configuration and hence won t reflect changes to the underlying objects unless the item configuration(s) are changed. Both pinned and floating readonly views are occasionally useful for read-only applications such as build scripts.! Variant view: In contrast to a reference view, a variant view is not a pure subset of its parent view. Instead, the objects to which it refers may branch when updated, although each item s branch-on-change behavior can be set individually. Consequently, variant views are also called branching views. How the view s items are initially configured cause variant views to behave in very different ways: 16
View Configuration Practices " Branch-none view: If a variant view s items are initially configured with branch-on-change set to false, it acts like a reference view, except that the view doesn t share labels with its parent. If the view s item configurations are set to float, updates through those items will float to the parent. (This is sometimes called a floating view.) If item configurations are configured to a specific timestamp, those items will be read-only. Some users have tried to create branch-none views and hand-tweak item configuration and branch-on-change, but this approach has proven tricky at best and sometimes disastrous. Consequently, branch-none variant views are not advised. " Branch-all view: Branch-all variant views are perhaps the most useful of all views. All items are initialized with branch-on-change set to true, hence they can be updated regardless of their configuration. Setting the item s initial configuration to floating versus a specific timestamp makes the view useful in different ways. This topic is discussed further under Development Scenarios. The basic properties and usefulness of the various view types are summarized in the following table: View type Reference versus Variant Shares labels with parent view Items can branch Items can be updated Usefulness Non-derived N/A N/A Only if shared Yes Low Updateable reference view Read-only reference view Reference Yes No Yes Low Reference Yes No No Medium (for read-only applications) Branch-none view Variant No Initially No Only if floating Medium (tricky to manage) Branch-all view Variant No Yes Yes High 5.2 Do s and Don ts of Views Irrespective of view type, below are some general do s and don ts to consider when creating and managing views. 5.2.1 DO Treat Views As Streams Treat each view as a stream for a specific lifecycle activity. The view may receive lots of updates, few updates, or none at all depending on the type of activity it supports. 17
View Configuration Practices 5.2.2 DO Use The Main View as the Main Baseline Use the main view as the project s production baseline. As such, it will accumulate all artifacts for the applications or components supported by the project. Depending on your lifecycle model and the size of your development team, changes can be made in a variety of ways, as discussed later. However, changes eventually migrate up to the main view. 5.2.3 DO Use Branch-All Views Make branch-all views your primary workhorse. Use reference views for read-only activities such as build scripts. 5.2.4 DO Use View Labels and Promotion States View labels and promotion states are easy to use and efficient. With a view label you can quickly mark all artifacts in a view, perform check-outs and builds based on the label, and adjust the revision of individual files that are included in the label. Promotion states allow you to define logical lifecycle states such as engineering test or release candidate and map each one to a view label, which can be adjusted or easily promoted to the next state. New views can also be created based on view labels and promotion states. 5.2.5 DON T Go Beyond 2 or 3 View Levels Views are generally only needed as immediate children of the main view. Third-level (grandchild) views are occasionally necessary. View levels deeper than 3 probably mean you probably aren t using views efficiently. 5.2.6 DON T Use Some View Types Don t use non-derived views, floating views, or updateable reference views except in very special circumstances where you thoroughly understand the behavior of these view types and that behavior best matches your use case. 5.2.7 DON T Use Too Many Views Views are somewhat heavyweight objects: They can take many minutes to create when derived from an existing view with many items, and they typically add thousands of new child items to the database. It s safe to up to several hundred views in a single StarTeam server, but you don t want to have thousands of views. This means that views don t work well as a personal workspace for individual developers. 18
View Configuration Practices 5.3 Use Views to Support Iterative Development Scenarios This section describes various iterative development scenarios and suggests how views can be used to support each one. For each scenario, the following assumptions are made:! The main view is used for the production baseline.! The project is configured to enforce process items, hence a CR, task, or requirement object is created for each unit of work. A unit is loosely defined to be the amount encompassing the check-in of a related set of files.! View labels (and possibly promotion states) are used for routine builds. This means, for example, that a nightly view label is applied from which a build is generated and then tested. View labels, promotion states, and process items are used to support intra view update steps. 5.3.1 Scenario 1: Small Development Teams For small development teams and/or short-term work activities, developers can use the main view directly. Child views are created when a release milestone is reached and subsequently used for release maintenance. The small team development scenario is illustrated in Figure 3 - Small Team Development Scenario. Main View check-out with lock check-in with process item and unlock mod mod mod mod mod mod Support View for release 1.0 branch-all view created from view label support patch Support View for release 1.1 support patch support patch Figure 3 - Small Team Development Scenario The activities used to follow this development scenario are summarized below:! When a modification ( mod ) is needed, a developer checks-out the required files from the main view, locking those that will be modified. After making local work file changes, including the creation of any new files needed, the developer performs sufficient unit testing to ensure that files can be released to other developers. When finished, the developer checks-in the new and modified files while unlocking, using a process item to link the revisions to the applicable CR, task, or requirement.! An automated script (not depicted) runs periodically and creates a new view label. Check-outs are made from the label to perform builds and launch test suites.! When the main development stream reaches a release milestone (e.g., after code complete), a branch-all variant view is created from a specific view label (e.g., Build 5.3.142 Release 19
View Configuration Practices Candidate ) or promotion state (e.g. Integration Test ). The variant view is used as a support view, since the only changes made to it will be critical defect fixes. Primary development continues in the main view.! If a change made to the support view is deemed applicable to other (future) releases, it is merged up into the main view as well (not depicted). View compare/merge is usually not required for this since the main view continues to evolve while the support view remains relatively constant with respect to a specific release. Instead, individual files are merged up to the release view.! This process repeats for each major release, creating multiple support views over time. Sometimes, the support view itself may be split off to a third-level view, for example to support service packs. This should be rare, however. If many server pack support views are created, causing lots of perfile merging one of the other iterative development scenarios may be more appropriate. 5.3.2 Scenario 2: Large Development Teams If your organization has longer-term work activities that are typically performed sequentially, you may not want to allow changes directly to the main view due to the periods of potential instability that may occur. Instead, you may want each project to reach a stable point (e.g., unit test or integration test) before it is released to the main view. To support this model, when a new work activity starts, you can create an activity view. (The term activity is used to avoid confusion with the term project, although project view is also an apt name.) An activity view is a branch-all variant view whose item configurations are set to floating. Hence, changes in the parent view will be propagate down to the child view. However, as a variant view, the activity view will branch any item if it is modified through that view. When the activity reaches the appropriate milestone (e.g., passes integration test), it is released to the main view by performing a child-to-main view compare/merge ( merge up ). The activity view then becomes inactive and may eventually be deleted. This model isolates changes for major new activities from the main view. The activity view scenario is depicted in Figure 4 - Activity View development. Main View merge up Activity View 1 Activity View 2 Activity View 3 mod mod mod branch-all view created from view label mod mod mod Support View for R1.0 Support View for R1.1 support patch support patch Figure 4 - Activity View development 20
View Configuration Practices When one or more sequential activities have been merged into the main view, a support view as described in the previous section is created for release-specific maintenance. 5.3.3 Scenario 3: Concurrent Development Activities In large development environments, development projects often are not sequential. Instead, you may need to launch multiple concurrent activities that must eventually be joined and then released together. Each activity must not only pass its own development and testing stages, but it must also pass integration testing with other activities before it can be released to the main baseline. In these environments, merging activity views directly into the main view may result in unacceptable periods of instability. In this scenario, two changes from the previous example are suggested. First, the activity view should be created as a branch-all variant view whose item configurations are initially set to a known view label. Periodically, the activity view can rebase with the main view by merging down from the main view, causing the item configurations to move forward in time. This allows changes from other activities that have been merged into the main view to be merged back into the activity view on a controlled based. Second, when multiple activities are ready to be merged together, a release view is created. (A release view could also be called candidate release view.) Like the activity views, the release view should be a variant branch-all view whose items are initially based on a known configuration (e.g., view label). Each activity view targeted for the same release is then merged into the release view using view compare/merge. After the activity-to-release sibling merges are complete, the release view undergoes integration testing. Changes required as a result of testing are made in the release view. Eventually, when the release is approved, it is merged up to the main view. In this scenario, a separate support view is usually not needed since the release view can assume the role of the maintenance stream. The concurrent development scenario is depicted in Figure 5 - Concurrent Development. Main View merge down R1 mod R2 R3 A1 (R3) mod A2 (R1) A6 (R4) A3 (R2) R4 A5 (R3) mod A4 (R4) Key: An (x): Activity View targeted for release x Rn: Release View for release n Activity views are branch-all float views Release views are branch-all fixed views All views are 2 nd level child views = merge from main to child view = merge from child view to sibling view or main view Figure 5 - Concurrent Development 21
View Configuration Practices Key points of this example concurrent development scenario are summarized below:! A new activity view (prefixed A ) is created whenever a new major activity is launched. An activity view is a branch-all variant view with configured (non-floating) item configurations.! A new release (prefixed R ) is created when the first activity is ready to be delivered to the release stream. A release view is created in the same manner as an activity view.! Before an activity view is merged into a release view, it is first rebased with the main view to accept any recent changes (e.g., other releases or mod changes). This is accomplished by a catch-up merge down, denoted by the downward-pointing dashed arrows.! Similarly, after all activity views have been merged into their target release view, the release view is rebased with the main view.! A release view is deployed by merging into the main view. This is done by performing a merge up, denoted by the upward-pointing dashed arrows. The release view then changes roles as a support view.! Minor changes ( mods ) are made directly to the corresponding view activity, release, or main using process rules for control. By adjusting the procedures for creating and managing activity and release views, you can tailor this process to match the concurrent development needs of your environment. The more sophisticated your development process, the greater your need is to tailor the process to your requirements. 22
Other Tips and Techniques 6 Other Tips and Techniques 6.1 Achieve Consistent Check-in and Check-out In all of the above scenarios, developers can use various StarTeam features to allow or avoid conflicts with other developers on the same files (in the same view). In a low-contention environment, developers can check-out files without locks, modify them, refresh to identify and resolve merge conflicts, and then check-in modified files. In higher contention environments, your developers may want more assurance of:! Consistent check-out: getting consistent sets of files during check-out, that is, avoiding files that are a partial set of someone else s check-in, and! Consistent check-in: avoiding check-in conflicts that arise when someone else is checking-in an overlapping set of files The easiest way to achieve both needs is by convention. Each developer exclusively locks all files before checking them in, and unlocks them when they are complete, either at check-in or soon thereafter. Correspondingly, each developer exclusively locks all files before checking them out, and unlocks them when complete. If a developer can not get all the locks at once, they are potentially about to interfere with another developer, so they unlock files they currently have locked, wait a bit (probably talk with the developer they are conflicting with), and then try again. One implication of this by convention approach is that a developer could be blocked while waiting for another developer to finish-up. A more formal way to enforce consistent check-outs is using view configuration. To ensure consistent check-outs without locks, a developer can temporarily change their view configuration to a known stable point. In some organizations, a nightly build process creates a view label when the server is not used or lightly used. To temporarily change the view configuration from the Win32 or cross-platform client, select View Select Configuration Labeled Configuration and choose the latest build label. (Alternatively, choose a timestamp or promotion state.) The view will switch to show the item states at the selected time, and consistent check-outs can be performed from there. Note that the view configuration change is only at the client the underlying real view is not modified. Also, note that rolled-back views are read-only: they must be reset to the current configuration before new/modified files can be checked-in. An implication to be aware of with this approach is that the time to switch the configuration can take a few seconds to a few minutes on very large views. 6.2 Simplify Merge Down with Branch-All Views If you use a branch-all variant view with item configurations set to a specific timestamp, you may periodically want to rebase the view by performing a merge down from the main view. This can be done with the view compare/merge tool. However, when a branch-all variant view is used as an activity view, many files will not have been modified and hence will not have been branched. In this case, the non-branched files can be more quickly rebased with the main view by simply altering their configuration timestamp. Using the Win32 client, this shortcut can be performed with the steps below:! Right-click the column heading again and select Sort and Group. Click Show Advanced Fields.! Change the sorting/grouping order so that the display groups by Branch State followed by whatever else you normally like to see (e.g., sort by status, then name, etc.) Click OK. You ll see all the files that have not yet branched grouped together under Not Branched.! Right-click the non-branched files and select Advanced->Behavior. On the Configuration tab, change the Configuration date to a new timestamp (e.g., the latest view label) and click OK. 23
Other Tips and Techniques An example of the Win32 client UI to perform these steps is shown in Figure 6 - Simple "Rebase" of Non-branched Files. Create a filter to group by Branch State Change non-branched items configuration time to known point Figure 6 - Simple "Rebase" of Non-branched Files This effectively rebases all non-branched items to a newer configuration from the parent view. This is faster than view compare/merge and allows you to rebase the view on a controlled basis. The branched files, of course, have to be merged separately. It is also helpful to set-up custom filters with the appropriate sort and group behaviors to make this easy. 6.3 Know What Operations Are Expensive Most of the day-to-day StarTeam operations you need to perform are fairly quick. However, a few functions are considerably more expensive on the StarTeam server and can impact the responsiveness of all users if performed often or during peak periods. If possible, these operations should be scheduled for off-peak periods.! Create derived view: Creating a derived view requires copying each item from the parent view to the child view. Consequently, new views created from large parent views can require thousands of new items to be created, causing the server to become heavily loaded until the new view is created. During that time, other users can experience response delays. It is best to schedule new view creation for off-peak hours.! Roll-back view: Temporarily rolling-back a client view can cause a momentary surge in server processing in order to fetch the item revisions for the new rolled-back view.! Label exceptions: When a new view label is created, it includes all revisions of each item that were in place as of a specific timestamp. The revision of individual objects that are attached to that view can be adjusted independently, but each such adjustment creates a label exception object. As a view label receives more exceptions, the time to retrieve objects based on that label 24