View Labels

View labels should be used to mark configurations of the entire view that match specific milestones such as a new build number, a point from which another view was created, a release candidate, and so forth. Consequently, you don’t create or use view labels for specific check-ins. Instead, you create them when one or more changes have been committed and it’s time to launch a new build, spawn a release view, or promote changes to another view. The following two scenarios illustrate good uses of view labels.

The following two scenarios illustrate good uses of view labels.

Scenario 1: Daily Builds

Whether your team prefers daily builds, nightly builds, hourly builds, or builds on demand, this approach creates new view labels where “Use as build label” is selected:

  • To get the process going, first create a view label as of a specific timestamp and launch the build process. (Some users prefer to have the build process itself create the view label.)
  • The build process then checks out files attached to that label and launches compiles, links, and other build tasks. If these tasks are successful, the same build process could also launch unit tests and other verification tasks.
  • If all build tasks are successful, the view label could be marked as “frozen”, which identifies it as a “good build”.
  • Conversely, if a build task fails, the build process could generate a report or notify someone via email. If you’re early in the development activity, you might choose to just move forward, allowing the team to continue making changes in the view. The next build process will simply “try it again”. When you’re later in the development activity, you’ll want to have the appropriate developers fix their errors, re-attach the new revisions they create to the same view label, and perform the build again. Only when you achieve a “good build” is the view label marked frozen.

The advantage of this approach is that it tends to ensure that the tip revisions in a view are generally buildable. This supports a growing software development practice known as continuous integration. The disadvantage of this approach is it may be difficult with large teams and environments with lots of changes. It can result in a lot of broken builds, finger pointing, and “nasty gram” emails.

Scenario 2: “Change” Builds

Instead of relying on tip revisions being generally stable and buildable, another approach is to create view labels that are attached to revisions that are carefully selected. The steps that take this path are outlined below:

  • Assume you start with an existing “good build” view label. As with the previous scenario, this label would be flagged as a build label and probably frozen.
  • Although many changes are occurring in the build, you want to select only specific changes as candidates for inclusion in the next “good build” label. To do this, ensure that the corresponding file revisions are attached to a revision label and that this label is only attached to the file revisions you’re interested in.
  • Start the next “good build” label by “cloning” the current label. In the StarTeam Cross-Platform Client, select View > Labels > View tab > New. In the corresponding dialog, choose Labeled configuration and select the current good build label. Your new label will now be identical to the old label.
  • Select the file revisions associated with the desired changes. In the File tab, select Select > By Label and choose the appropriate revision label.
  • Now attach these revisions to the cloned view label. In the File tab, select Labels > Attach. In the corresponding dialog, select the cloned label in the upper label list. In the “Attach to items at” group box, select “Labeled configuration” and choose the same revision label you used in the previous step. This ensures that the correct revision of each file is attached to the cloned label, otherwise the tip revision will be attached, which may be the wrong revision.
  • Repeat the previous two steps if there are multiple revision labels representing file revisions that should be included in the new label.
  • Now launch the appropriate build and test process for your new “good build” label. Mark the label frozen or reattach fix revisions and retry as in the previous scenario depending on whether the build/test process succeeds.

This approach allows you to tag view configurations as candidates for builds, promotes, etc. without relying on the tip revisions being stable. The disadvantage of this approach is that if your latest “good build” label is way behind the view’s tip configuration, the quality of more recent changes may not be known for a while (which goes against the premise of continuous integration.)

Because this approach employs label “cloning”, there is a caveat we should mention with respect to deleted items. Suppose an item is attached to a view label and then deleted from the view. As you’d expect, when you “time travel” by adjusting your view window back to the view label, the item “reappears” because it existed when it was attached to the label. Less obvious, however, is that when you clone the label, the item will also be attached to the new label because the new label is initially identically to the old label. If you don’t want items deleted in the tip configuration to be attached to a cloned label, just detach them from the cloned label.