The Change Package Object

A change package is a StarTeam object that is persisted in the repository’s database. A change package object is used to store information defined in a View Compare/Merge session when it is saved. In this state, a saved View Compare/Merge session is presented to users as owned by the target view. When the View Compare/Merge session is committed, it is still presented as belonging to the target view, but it is presented as a committed change package that can be queried and reused in additional ways.

A View Compare/Merge session can be created at the client and committed without ever being saved, consequently it is possible to create a change package object in the same transaction that applies its updates. When this occurs, the View Compare/Merge session is never shown as a saved change package. This is desirable for quick change sessions, for example, a View Compare/Merge promote of a few items.

The following are features of a change package object:

Owned by a single view, the target view. It is on par with other view-owned objects such as labels and promotion states.
Cannot be copied, moved, or shared to another view (although it can be replayed as described elsewhere.)
Since a change package cannot be shared, the tip revision is always shown in a “current” configuration of the target view, and it cannot be pinned. Consequently, it does not have configuration properties such as Branch On Change or Configuration Time.
Do not reside in folders. All change package objects belong to the view object and do not have path-related properties.
A new revision is created each time an existing object is updated. A change package is updated whenever a View Compare/Merge session is saved or committed. Essentially, the pre-committed change package becomes the committed change package. A committed change package is read-only and can no longer be changed (except for its revision comment).
Behave correctly with respect to “time travel”. That is, when a user sets the target view configuration back in time, and change packages will appear as they did as of the rolled-back time.
Can be attached to view labels. This allows, for example, users to attach a change package to a build label to indicate it was included as part of that build. Label attachment also allows two view labels to be compared to see their differences in terms of change packages. A change package also has a Committed in Build property which is set to Next Build when the change package is committed. The property is automatically modified to point to the next build label created. This feature allows change packages to identify the first build in which their changes were included.
Prior to being committed, a change session can be deleted. As with all versioned objects, the delete is “soft” meaning the change package will no longer appear in the tip revision of the target view. However, if the target view is rolled back in time, a previously deleted change package will “reappear” and can be opened in read-only mode. However, there is no way to “undelete” a change package. After a change package is committed, it cannot be directly deleted. Committed change packages are deleted only when the target view is deleted. Database information no longer needed by a deleted change package is removed during the database purge process.
Can have queries and filters. This allows change packages to be displayed in the StarTeam Cross-Platform Client with popular sorting, grouping, and filtering criteria.

In addition to the StarTeam Server’s persistence and versioning service, change packages also use the server’s locking service. This means that a change package can be locked exclusively or with a shared lock. An exclusive lock is automatically applied to a saved change package when it is opened for editing. A change package can also be opened in read-only mode, though a non-exclusive lock is not applied for this use. Change packages cannot be “flagged” (bookmarked). Internally, change package objects also use attachments to store options and session state.

Change Package Security

Change packages have similar access rights as other view-level objects such as labels and promotion states. The ability to perform specific updates while committing a change session are derived from the permissions of the target view. For example, the ability to check-in a new revision of a file is derived from that permission in the target view.

An administrator can grant or deny the following view-level rights to any user or group:

Create change package: Users who do not have this right for a given view can start a change session for that view (in the client application), but they can only save it to an external file format; they cannot save it persistently in the database.
Modify properties: Users who do not have this right for a given view cannot create a new revision of a change package for that view, for example, by re-saving or committing an already-saved change package.
Delete from view: Users who do not have this right for a given view cannot delete a saved change package in that view.
See change package and its properties: Users who do not have this right for a given view cannot access change package objects for that view.
Change access rights: Users who do not have this right can not modify change package access rights.
See history: Users who do not have this right cannot see historic revisions of a change package.
Set exclusive locks: Users who do not have this right cannot acquire and exclusive lock on a change package. this means that they cannot edit a saved change package.
Break exclusive locks: Users who do not have this right cannot break an exclusive lock currently held by another user.
Label rights: These rights control the ability to change what labels a change package is attached to. They include: Attach/Adjust view labels, Detach view labels, Attach/Adjust revision labels, and Detach from revision labels.

Note: Change package access rights are enforced with the same group/user/container resolution hierarchy as for other security ACLs.

Change Package Replay

You can select a committed change package and apply the same changes to another view. This capability is termed replay. A change package selected for replay is termed the source change package, and the view that it originally updated (originally the target view) is termed the source view. The new view to which the updates are to be replayed is termed the replay target view. The replay is identical in function to a View Compare/Merge merge in which the items updated by the source change package are selected as the source scope and merged to the replay target view.

When a change package is replayed to another view, a new change package is created for the new target view. The new session acts as the staging area for the replayed changes so they can be reviewed, adjusted, and so forth before being committed to the new target.

If the replay target view is a parent of the source view, the replay is performed as a View Compare/Merge promote.
If the replay target view is a child of the source view, the replay is performed as a View Compare/Merge rebase.
If the replay target view is not an immediate child or parent of the source view, the replay is performed as a View Compare/Merge replicate.