Labels

In version control, the term label corresponds to the act of attaching a view or revision label (name) to one or more folders/items. StarTeam enables you to create two types of labels:

View labels: Are automatically and immediately attached to all folders and items in a view at the time you create the view label. View labels have multiple purposes, but you primarily use them to place a time stamp on the entire contents of the view and as build labels. When you roll back the view to that label, you see everything that existed at that point in time—unless the label has been adjusted. You can create a view label for a specific point in time or as a copy of another existing view label. Unless the view label is frozen, you can adjust it to include or exclude some folders and items by attaching or detaching view labels. You can also move a view label from one revision to another.
Revision labels: Are not attached automatically to any item in the view. Instead, they are used to designate a set of folders or items within a view. For example, you might want to label a group of files that should be checked in and out together. After you create a revision label, you attach specific items, building it up to reflect a specific set that is typically a small subset of the view. StarTeam can automatically attach new file revisions to a revision label at check-in time if you like.

About Labels

You can attach a label to any type of StarTeam item, including folders, files, requirements, change requests, tasks, topics, and audit entries. Any item can have more than one label. However, no two revisions of the same item can have the same label at the same time.

Every label is unique within its view. That is, no view label can have the same name as any other view label, no revision label can have the same name as any other revision label, and no view label and revision label can have the same name. Each view has its own set of labels. This also means that every label has a name that must be unique from other labels belonging to the same view. Each label also has a description that helps users understand the purpose of the label.

You can manually attach or detach both view labels and revision labels to or from a folder or item. In addition, you can use either type of label to identify a file when it is checked out. When you check a file in, you can attach and create a revision label for that file or attach an existing revision label.

You can select any type of item by its label. For example, you can select all files with a particular revision label and roll them back to that label, making the revision with that label the tip revision. Then you can compare your working files to the rolled-back revisions.

You can set access rights for labels at the view level or at the folder or item level. You must grant the rights to create labels, edit their properties, and delete them at the view level. However, you can grant the right to move a label (also called adjust a label) at the folder or item level.

A label can be frozen, which means no new artifacts can be attached to it, and attached artifacts cannot be detached nor reattached at a different revision. Conversely, non-frozen labels can have all of these modifications. Since many organizations depend on the immutability of frozen labels, a specific security permission is required to freeze or unfreeze a label.

StarTeam actually attaches specific item revisions to a label, each of which infers a specific artifact revision. Since each item specifies a parent folder, the artifact is attached in a specific folder. This means that if you move an item, you need to reattach it to any label for which you want to reflect the artifact in its new folder. If you don’t reattach a moved item to an existing label, it will continue to be attached to the label in its old folder (which may be what you want).

Even if frozen, both view and revision labels can be cloned. That is, you can create a new label starting out identical to an existing label and then adjust the revisions attached to it. A common practice is to clone a previous label, attach only new file revisions that were created to fix a bug, and use the new label to identify the file revisions for a new build candidate or release candidate.

Time Stamps and Build Labels

Using a view label as a time stamp, you can roll a view back to see everything in the view as it was at the time the label was attached. For example, to see if a particular file was in the beta version of a product, you can roll back the view to the beta label.

You may also use a view label as a build label, which allows the QA team to immediately determine what build to test for a fix to any given change request. To use a view label for this purpose:

It must be designated as a build label.
It must be created while the Addressed in build property for the change request contains the value Next Build.

When StarTeam creates the label, each change request with Next Build as its Addressed in build property will be reset to the build label.

To create a view label, you must select the current configuration of the view. Historical configurations are read only, and adding a label is considered a change. However, if a label already exists for a prior configuration, you can adjust its name, files and folders can be added to it or detached from it, and so on. You can also move a view label from one revision to another.

For example, suppose your administrator creates a view label before each build, giving that label to the tip revision of each file in the view, and then checks out all the files with that label for the build. If the tip revision of one file does not change for a few weeks (or longer), it can acquire several view labels, while a file that changes frequently may have several revisions with no view labels and other revisions with only one view label.

When you detach a view label from a folder, StarTeam automatically detaches the label from everything in the subtree for which the folder is the root. If you roll back a view to a specific view label and a folder does not have that label, you cannot see the children of that folder and their contents anyway.

You can only create a view label at the view level and only while the configuration is current. However, you can create a view label for the current configuration or for a time in the past. In either of these two cases, StarTeam attaches the new label to the tip revision of each folder, file, change request, task, or topic that belonged to the view at the specified time.

You can also create a view label as a copy of an existing view label or as a copy of the view label currently attached to a promotional state. In these two cases, StarTeam attaches the new label to exactly the same items and revisions as the existing view label.

You can check file revisions out using this label or roll back the view to this label and see all the items associated with that label. For example, if you create the view label Build 100 as you make Build 100 of your product from a view, all the files in the view will have the label Build 100.

If some items should not be included, you can detach the label from those items individually. For example, if some files should not have that label, select the files then select Labels > Detach from the File menu or context menu to detach that label. If the files that should not be included all belong to the same folder and are the only files in that folder, use the Labels command on the Folder menu. For example, if the help files were not checked in until after the view label was attached, you can move that label from the previous revisions of the help files to the newly checked-in help files.

Label Access Rights

You can set access rights that apply to labels at the view level and at the folder/item levels. You set the access rights that allow a user or group to create labels, edit their properties, and delete them at the view level. For example, if you can create a label, you can set its initial properties. However, if you do not have the right to edit label properties, you cannot later freeze or unfreeze that label.

You can attach labels to individual folders or items, detach from them, or move from one of their revisions to another. The access right to move a label is named Adjust a label. You can grant or deny these rights at the folder or item level.

Example View and Revision Labels

Note: Not all items in a view have to be attached to a label. Conversely, an item can be attached to any number of view and revision labels as you like, but only one revision of an item can be attached to any specific label.