View Labels and How to Use

Send this document to a colleague

View Labels

Another attribute of a StarTeam View is the list of View Labels. View Labels are used to identify static configurations containing specific versions of Items in a View. When you create a View Label it stores a timestamp for the View that it was created in. This takes advantage of the basic Item versioning features of the StarTeam Repository by efficiently labeling the configuration of versions. In essence a View Label gives you a static snapshot of the dynamic View that it was created in.

Changes can be made to the specific Item versions associated with a View Label by dragging a View Label from one version of an Item to another in the Label pane. Typically a View Label will contain a small number of these label changes while the majority of the Item versions are identified by the timestamp stored when the View Label was originally created.

Use View Labels to indicate development milestones such as a daily build. Then you will be able to return to the precise configuration of specific revisions at a latter time by using the Select Configuration command in the View menu or /CFGL option on the command line check-out command.

Uses Cases
StarTeam realizes that each environment has unique structures, policies, processes and SDLC?s that work best when applied within their software environment. StarTeam?s overall goal is to model your SCM methodology within our tool using various items (i.e. views, branching, merging, labels, promotion model, etc.). The following is a brief introduction to some ?Uses Cases? that our current customer base utilize within their software environment, as well as some models and the best way to set these cases up in StarTeam.

Release Development and Main Development

Freezing the codeline during release activities is not an option with StarTeam. StarTeam handles release development and main development in a number of ways. The following brief scenarios will be familiar to your SCM environment.

Sample Scenario:
During the development cycle both Joyce and Mike will have changes that will need to be checked into StarTeam for Release 1. However, Joyce finishes a couple of weeks before Mike. While Mike is still working on these changes, Joyce will need to work on the changes for the next Release without affect Release 1. How do I ensure that the items Joyce checked into StarTeam will not freeze continued development in the main line and when Mike is done with his changes they will be incorporated in Release 1.

Labels

One approach to handling the above scenario is the use of revision and view labels. A revision label provides a convenient method of identifying a revision of an item or a set of revisions by name. This is primarily used for files. View labels apply to the latest revisions of all the items in a view?until moved or removed.

StarTeam allows you to label the most recent revisions of every item within a view. For example, when the project reaches a particular milestone (such as beta), you might give the view?s items a label, called a view label. Then you can configure the view to return to the way it was at the time the label was applied, check out revisions as a group using that label, create a new view based on the label, or assign the label to a promotion state.

In this scenario the user would perform the following steps:

• After Joyce is done with her changes for "release one," she will create a revision label for her files (call it "beta release one") and continue developing for the next release.

• Upon Mike?s competition of his changes for "release one" he will create a view label (call it "prod release one").

• Mike will then (using StarTeam 4.1 only) query by label to find Joyce?s revision label (called "beta release one").

• Once the queried files are selected ("beta release one") Mike will then attach the view label ("Prod release one") based on the label configuration ("beta release one") to those files.

Sample Scenario:
Mike is the project coordinator and StarTeam administrator for a project team that is releasing software to production and in parallel maintaining development for new releases. How does Mike handle all of the project releases while allowing other development to continue to take place on the main line? Does he freeze the codeline during release engineering activities?

Promotion Model

Instead of freezing the codeline during the release engineering activities, StarTeam uses labels, promotion models, and branched views. The process would include:

• Create a View Label upon the completion of development.

• Using the Promotion model, the user will need to define various states e.g. Development, Testing, QA, and Release.

• Under Views/Promotions the user will promote the view label through the various states.

• Based on the state, which in this case the desired promoted state of the view label is ?Release?, the user will create a branched view derived from the current view and base the configuration on a promotion state.

A separate line is created for release integration and engineering while allowing other development to continue taking place on the main line.

Bug Fixes

StarTeam offers it users the ability to create Fix Branches off the main line of development for the purpose of fixing bugs. When the bugs are fixed the Fix Branch then merges back to the main line of development.

Sample Scenario:
During the development cycle both Joyce and Mike will have changes that will need to be checked into StarTeam for Release 1. During the development Joyce realizes that there is some bug fixes she?ll need to make from the main line of development, however she does not want to affect development on the main line. What is the best practice or steps for Joyce to handle these bug fixes?

Branching for maintenance

When maintenance and parallel development need to occur simultaneously, StarTeam recommends the use of branching and merging. This process would include:

• From the main line of development derive a new view from the current view.

• Permit items to branch and branch all.

• Follow the wizard (ie. Give it a view name, new working folder, select folder to branch and base it from the as of configuration).

• Perform all of your bug fixes from the Maintenance View.

• Upon completion of your bug fixes select the ?Compare/Merge? option under ?View? to merger your items back into the main line of development.

Completely Independent Development of Products

StarTeam allows users to create a separate line of development for independent development efforts. Creating an independent or variant development line from the main development line can be accomplished in StarTeam at the current revision, labeled configuration, Promotion State or as of date and time configuration.

Scenario Sample
Developers Joyce and Mike are developing code from the main line of development for Product A, Tim and Jill need to branch from the main line of development for Product A1. Product A and Product A1 are independent products and need to have their own files, task, topics, change request, and labels.

Branching Independent Development of Products

When developing independent product, StarTeam recommends the use of branching. This process would include:

• From the main line of development derive a new view from the current view.

• Permit items to branch and branch all.

• Follow the wizard (i.e.. Give it a view name, new working folder, select folder to branch and base it from the as of configuration)

Common Component Library Development

An additional level of organization can be achieved in StarTeam by linking separate Projects together. These individual StarTeam projects become a much larger unit. The typical use for this layer of organization is when a single product has several very important sub-components that will combine to make a whole Product. What you lose is simplicity of use, as managing several sub-components (projects) can make administration of that product a little more difficult. The advantage of breaking up a Product into separate sub-components is the greatly enhanced flexibility of each component, which can be easily labeled, branched, and sent through it's own promotion model sequence independently of any other component in the product.

A product may be composed of multiple sub-components or sub-systems (Fig. demonstrates a product with seven sub components, A - F).

Fig. 1 Projects under one StarTeam Server repository:

In the above illustration, seven StarTeam projects are created that exist independently of each other. The six projects, A - F are sub components of a single product, that when all checked out to the same location, will compile into a single product. The seventh StarTeam project, Common, is a project of common code that is shared into each of the previous six projects (A - F) . By sharing the common code, you can make it easily accessible from any sub-component, and when you make a change to the common code in the any share, or the Common project itself, all other projects will immediately see the benefit of the change.

Setting up the build process:
The above is just a basic example of the layout of a product with sub-components, and individual cases may vary slightly. However, by placing each sub-component as its own StarTeam project, each sub-component can easily be labeled, branched and promoted on its own cycle, independent of the other sub-components. This allows a considerable amount of freedom per sub-component, but it does require some additional work when the time comes to actually reconstruct and check out all the sub components into the product they are intended to become. The easiest way to initiate a build process is through the use of the StarTeam command line.

Checking out by Build Label:
Below is an example of a typical batch file that might be created to construct a build from the seven projects in Fig. 1. Each sub-component is checked out based on its own build label: Project A - Build 5, Project B - Build 2, Project C - Build 3, Project D - Build 7, Project E - Build 1, Project F - Build 3. The checkout process will only grab the version of the files with the respectively attached Build label. All files from all projects are checked out to "C:\production build". This entire batch file will create the product. In order to produce this build easily in the future, without having to remember what label was used for each component, check this build.bat back into StarTeam with a build label for the product. In the future, if you want to recreate this build, you can merely check out the build.bat from StarTeam and execute it.

Ex. 2 (build.bat)

@ccho off
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project A/Project A" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 5" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project B/Project B" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 2" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project C/Project C" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 3" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project D/Project D" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 7" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project E/Project E" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 1" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project F/Project F" -is -x -q -o -fs -rp "C:\Production build" -vl "Build 3" *

1. Note: These are project and not views.

2. Note: users are not allowed to check-in on share folders. Additionally, if users want to delete a file from the common folder it will not ripple through to all the shared folders into. The user will need to delete the file from each individual shared folder

Checking out by Promotion State:
Another useful batch file would be to check out by Promotion State. The advantage here is that you can quickly create a current build of your product without having to go through a batch file and set each up the batch with the appropriate labels for each sub-component. While this can be a great time saver, bear in mind that Promotion States float. So using this batch file to generate a build today could generate a different build tomorrow, depending on what labels have been assigned to what Promotion States. Fig 3 demonstrates a scenario in which each project (sub-component) has had a three stage promotion model setup. (For more information about setting up a promotion model, check the StarTeam user's guide Chapter 9: Using Promotion States). Each promotion state is assigned a corresponding Build Label. To get a quick check out of what would be considered the current production version of your product, you can run a batch file that will go to each sub-component and check out what all the files currently in the Production Promotion State.

Fig 3.

Ex. (Production.bat)

@echo off
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project A/Project A" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Production" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project B/Project B" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Production" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project C/Project C" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Production" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project D/Project D" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Production" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project E/Project E" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Production" *
stcmd co -p "Administrator:Administrator@Whitestar:49201/Project F/Project F" -is -x -q -o -fs -rp "C:\Production build" -cfgp "Production" *

Running the above batch would produce and identical checkout to the ex. 1, build.bat. However, if the "production" Promotion State of Project a is assigned Build 6 tomorrow, then running production.bat would generate a new build where build.bat would not. in order to roll back to previous builds easily, it is important to construct and use both batch files. Both files can be checked into StarTeam to preserve them for later use.