Introduction to best practice use of views



StarTeam uses a system of Projects and Views to structure checked-in code. Structuring the views effectively is an important consideration when setting up a StarTeam project. 

Consider the view structure below, which is considered standard best practice for StarTeam development:

In the above view structure, the Release subviews are used for development work on each release. Once a release is completed the View Compare Merge tool is used to promote these changes into the Production view. When work begins on a new release a new view is created called Release 3.0 and development work continues in that view.

The following section will outline how to build this structure.

Creating A Project


Open StarTeam and click Project | New

Select the server and log in.

Give the Project a name and description

Click Next

Enter a working folder path – this is where files will be stored on the local disk when checked out from the project for development:

Click Yes if warned about the non existence of the folder – it will be created later:

Click Finish

You will then be presented with a blank overview of the Project.

Right click the root folder and click “Create working folders”

This will create the local structure on disk.

Right click again and click | Open Local Folder

Place the source code for the project into the local folder:

Click Folder Tree | Show Not in View Folders

The folder tree will show with white folder icons indicating folders which exist on the local disk but not in StarTeam:

Click the Folder tab and click All descendents – ensure the root folder is selected in the left pane:

Right click the header showing “Not in view” and click “Add files”

Click OK – a description is not necessary – bear in mind any description added here would be added to all files.

Creating SubViews

In a best practice scenario, development is carried out in subviews. These are created as a subset of the main production view.

When the view is created, the content is copied from the main view (this does not consume extra space) – at the point of creation, the view is identical to its parent. Development can then continue in the sub view, without causing changes in the main production view.

To create – ensure the parent view is open in StarTeam.

Click View | New

Ensure the type “Branch All” is selected. This is the only type of view which is needed for development subviews in most cases.

Enter a name and description for the view

Click Next

An option is available to select a folder at which to root the view, the topmost (root) view should be selected in most cases:

Click Next.

Enter a working folder path for this view – this should not be the same as the parent view, or data loss may occur

Click Next

Click Yes if warned about the non existence of the folder:

Select the item types you wish to include in the Branch view. You may wish to include Change Requests if they are also routinely edited during development.

Click Next

Click Finish

The new view is created.

Users will need to create local folders and check out files to begin development.

When files are edited, their status will change to Modified

In the following example, the file AFXCRMAC.RTF has been modified and will be checked in:

This process should continue until the release has been completed, at this time the View Compare Merge tool should be used to promote the changes into the production view.

Promoting A Release To Production Using View Compare Merge

Ensure the Release subview is open and that all development in the view is complete.

Click View | Compare /  Merge

Select “Promote” and ensure “source of merge” is selected

Click Next

Ensure “Current configuration” is selected:

Click Next.

Select the types to be merged – this will usually just be files.

Click Finish

You will then be presented with the merge perspective, which will show all proposed changes for the merge.

Click the All Descendents button

Note the green tick marks for the Product Name and Source Code folders. This tick mark signifies that changes have been made within this folder – but they have been automatically resolved for merge.

Note that only one file has been changed in this example, several will have changed for a true release promote.

Click VCM Session | Commit Changes

Click the pre-commit and post-commit view label check boxes

Click Commit Changes

You will be presented with the option to generate a report of changes, click “Generate Report” or “Close Session”

The following sample report shows the single file merged in this example

VCM Session Overview

VCM session parameters:


StarTeam Server


Merge type



Product Name

Source view

Release 2.0 Development

Source view configuration


Target view

Product Name (root view)


File, Folder

Change Package:



Promote Release 2.0 Development on 2012-06-08@09-54-57Z


Merge type: Promote Source view: Release 2.0 Development Target view: Product Name Scope: File, Folder

Transaction ID




Created By




Created Time

08/06/12 10:54:57 BST

Modified Time

08/06/12 10:54:57 BST

VCM session options:


Auto-merge files


Auto-merge properties


Default comment

Promote from Release 2.0 Development

Lock target items with differences


Match files by file name


Pre-commit view label

VCM 2012-06-08@09:52:17Z Pre-Promote by Ed

Post-commit view label

VCM 2012-06-08@09:52:17Z Promote by Ed

VCM application options:


Include types in view




Updates to View: Product Name

File updates by folder

Folder: /Product Name/Source Code/On-line Help/




Merged with source item AFXCRMAC.RTF (

--End of Report--


The changes will now be merged into production.


The view hierarchy allows for independent development within self contained subviews. When a new release begins, a new “Branch All” view is created from the production view.

Work continues in this view until a release is finished, at which time the VCM Promote option is used to promote these changes to production. A new branch all view is then created from production for the subsequent release and the cycle continues.


How To-Best Practice
Comment List