View Roles

This section describes the various types of view roles.

View Roles Overview

Technically, you could manage a project’s artifacts using only the root view. For example, you could:

Add all new folders, files, change requests, and other items directly in the root view.
Acquire locks as you modify items to prevent conflicts between users.
Employ revision labels and process items to identify revisions related to the same logical change.
Create view labels to mark milestones such as specific builds and releases.
Use promotion states to propagate snapshots represented by view labels through a coordinated test and release process.

When your project is first getting started, or if you have a very small (and safe) change to make, direct modification to the main view is fine. Otherwise, direct modification increases the risk of breaking the build if you haven't staged your changes elsewhere first. The moment your team needs to work on two versions of the same file, module, or application at the same time, it needs a place other than the root view to do its work. This is the purpose of development streams. You need containers that support parallel development or maintenance activities that require different artifact branches within the project. The child views you create under the root view provide these containers.

Because version control and SCM products have existed for several decades, it should be no surprise that many different patterns have been developed for managing software development artifacts. These patterns affect the number of development streams you deploy and how you propagate changes between them. With StarTeam, this translates to the number and type of views you use and how they are organized.

Most of the child views in your view hierarchy should be branch-all views. To determine when you need a new view, where it should live in the hierarchy, and whether a different type of view would be more appropriate, you should consider the role that each view will fulfill. Based on our experience, the best way to use views is to consider the roles described in the next sections.

Main View: Home Base for Artifacts

The main view, also known as the root view, should contain the latest, approved revisions for the whole project. By latest, we mean that the main view should match your latest changes, ready for the next release. By approved, we mean that it should contain revisions that have undergone whatever verification checks your process requires: a complete build, unit testing, integration testing, etc. By whole project, we mean that it should not be a subset of the project’s modules. In short, your main view should contain the latest, complete, production work, ready to be seen and used by everyone.

Implicit in this recommendation is that the main view should always be clean. That means it should be buildable and able to pass most if not all tests. Experience has shown that you will avoid many headaches by keeping your main view clean. To do this, all except for the simplest changes should be made in other views where they can be tested and fine-tuned until they’re ready to be propagated to the main view. Once a new or modified revision has passed the point of no return—you’re sure you won’t change your mind—only then should it appear in the main view.

There is a subtle but important interaction between the main views and “share trees” you should be aware of. In general, the main view should contain the main (1.n) branch of each artifact. This happens automatically when you add a new artifact in the main view. StarTeam first creates a new 1.0 artifact and then connects it to the view and parent folder with a new item. But suppose you create a new artifact in a child view and then share the item “up” to the main view. Since the child view item was created first, it will be the “root share”, and the main view item will receive a “child share” item (initially pointing to the same artifact). In other words, the item share tree will point in the opposite direction as the views. You probably won’t notice a problem until you modify the item in the main view, causing it to branch, thereby pointing to a non-main branch (e.g., 1.n.1.m). In future attempts to propagate changes between the two views, you’ll find that it gets harder to propagate changes correctly because the share tree is backwards. For example, “rebase” operations won’t work correctly. What can you do about this? The solution is to use the view compare/merge (VCM) facility to promote new items to the main view. VCM understands the share tree issue and propagates new items using an operation called reverse share.

Note: Savvy StarTeam pre-2006 users are aware of this subtle “share tree direction” issue and employ custom solutions. Some customers simply add new items to the root view first and then share them down to child views. Other customers propagate new child view items to a parent view by first moving them up and then sharing them back down, this is a basic version of what a VCM reverse share does.

Activity View: Isolated Team Work Area

Suppose your team is assigned with developing a significant new enhancement (or a set of enhancements to be developed together). By significant, we mean changes that will affect more than a few artifacts, take more than a few days, and/or involve more than a few people. You wouldn't want to make changes directly to the main view since:

You want to check in your changes often to ensure they are backed-up, progress can be tracked, etc.
It may be a while before your changes are sufficiently stable to begin testing. The way to isolate your team's work is with an activity view.

An activity view is a branch-all view created from a well-identified, stable configuration of the main view. If the enhancement work only requires a portion of the main view's modules, you might choose to root the activity view from something other than the main view's root folder. Typically, an activity view is created from a view label or promotion state, which causes it to contain items pinned to the same revisions in the main view as of that snapshot. As changes are made to the activity view, the corresponding items will branch and hence will not be visible to the main view. New items are also added to the activity view and hence not visible to the main view. As work progresses, the state of tip revisions in the activity view may not always represent a buildable release. But eventually, your team will build, test, fix, and finish its work, whereupon it is "promoted" to the main view.

Starting 17.0 release of StarTeam server, "lightweight activity" views should be used for working on activity views. Creating a 'branch-all' view can be a heavyweight operation for large views as all the items are shared down during view creation and shares need to be fixed up. While a branch-all view is still recommended for release views which required to be built and labelled, lightweight activity views are recommended for quick feature development/ bug fixes. Creation time for lightweight activity view is extremely fast and the view itself leaves a low footprint on the server and database making it ideal for activity views.

Activity views typically have a limited lifespan: when the enhancement work is done and promoted, they can be deleted, usually after a certain period of time. Strictly speaking, a single activity view could be used for multiple enhancement activities, but there is an advantage to using separate views for each activity: if for some reason the activity must be cancelled, the activity view can be abandoned and eventually deleted. This isn't practical if the view contains work from multiple activities. Either way, activity views periodically require "rebasing". A variation of the activity view is an integration view, which supports integration activities for a large software project.

Release View: For Post-Release Maintenance Work

When you release a snapshot of your software, you’ll probably have to maintain a development stream just for hot fixes, patches, service packs, and so forth. A view that fills this role is called a release view (or a maintenance view).

Like an activity view, a release view is a branch-all view created from the main view as of a specific snapshot. A release view is created after one or more enhancement activities have been completed and promoted to the main view. It represents a milestone where your software has been (or is about to be) released externally. The release view is almost always rooted at the main view’s root folder, and it is usually created from a frozen view label to clearly establish the software configuration that was actually released. In fact, many organizations create the release view first and then build and deliver the software from the release view.

Since it is a variant view, a release view can receive changes: for example, to fix bugs. If these bugs must be propagated to the main view, they are promoted as in activity views. However, release views are generally not rebased to receive changes from the main view except for bugs fixed in the main view first that must be applied to the release view as well.

If you need to make significant changes to a release view (perhaps a service pack), it is acceptable (even advisable) to create an activity view as a child of the release view. You would then make the changes in the activity view, perform appropriate validation tasks, and then promote it to the release view. You might even want to use a sandbox view, which is discussed below.

Build View: Read-Only Windows for Build Scripts

Many StarTeam customers create build applications using simple build tools (for example: make, nmake), a commercial build product, or open source components (for example: Ant, CruiseControl). It is easy to integrate these tools with StarTeam due to the availability of its full-featured SDK and the availability of pre-built components such as StarTeam Ant tasks and a CruiseControl “bootstrapper” plugin for StarTeam. Build applications typically open a view, specify a snapshot configuration (timestamp, view label, or promotion state), and then check out the files they need.

In some cases, however, an organization may want to restrict the access of the build tool (or user) in comparison to the permissions other users have to the view. For example, you may want to guarantee that (a) the build tool can see only artifacts required by the build (and not design documents or other artifacts), and (b) the build tool has read-only access and cannot modify anything.

This situation could be handled through folder- or artifact-level security rights. However, this situation occurs often enough that some customers have found it useful to create a view tailored to the needs of the build tool. Such a build view is often created as a read-only reference view based on a promotion state. The reference view may be rooted at a non-root folder of the parent view. Consequently, a limited set of artifacts are exposed, which cannot be modified. Whenever the promotion state is assigned to a new view label, the new artifact revisions automatically “appear” in the build view. That is, the build view follows changes to the promotion state.