Version management

Version management is the process of storing and tracking changes to product components over time. In Dimensions CM, you manage the versions of product components by using items and item revisions.

Items and item revisions

An item is an object that represents the physical implementation of an application component.

For example, an item in a software application could be source code, an executable file, a specification, or a user guide. An item in a web site could be an HTML file, a script, or an image file.

An item revision is a specific version of an item. Whenever you modify an item, Dimensions CM creates and stores a new revision of the item. The revision includes the state that the item is in after being modified. The file associated with the item revision is stored in operating system libraries controlled by Dimensions CM. Every revision is tracked and stored separately, so you can make sure revisions are not accidentally lost. Every revision has a full set of attributes, such as modification date, reason for change, and author's name, stored in the Dimensions CM repository, which enables you to trace the history of all changes to an item.

A directory item is an entire folder, including subfolders and files, compressed and stored in Dimensions CM as a single item.

A virtual item does not have its associated data file stored in Dimensions CM. It means that you can create items with no file content. Virtual items are used primarily for controlling hardware configuration items rather than software. You can use a virtual item to track all information about the hardware item with the help of revisions, attributes, and relationships.

Access to an item is controlled by the role assignments for the design part that owns it and/or the design parts above that.

Work with items

These are basic version management tasks in Dimensions CM:

Create an item.
Check out item revisions.
Check in item revisions.
Get copies of items.
Action item revisions to a next lifecycle state.

Dimensions CM provides a number of other features for processing items. Some operations with items can be performed in projects but not in streams. Commands that allow folders or items to be changed directly, either in terms of content or refactoring, cannot be used with streams. For details about streams and the differences between streams and projects, see the following sections:

Web client:	Work with streams
Desktop client:	Work with streams

In Dimensions CM, you can perform the following version management operations:

Operation	Description
Preview an item	Preview and print the contents of an item revision.
Copy an item	Get a copy of an item revision.
View history	View the action and revision history of an item. Desktop client only: You can also view item pedigree, which displays how item revisions are related.
View users, roles, and privileges	View the role assignments for an item, the users who have the item in their inboxes, and the privileges that are assigned for this item.
Create an item	Create a new item by adding a file to Dimensions CM. For details, see About creating items.
Check out and check in an item	Check out an item into your work area to edit the item, and check it in when you are finished.
Edit or revise an item	Web client: Update an item using a file in your work area without checking it out first. Desktop client: Edit an item without checking it out first, or update an item using a file in your work area. For details, see About editing items.
Edit attributes	Change the attributes of an item.
Action an item	Move an item revision from one state in the lifecycle to the next state.
Delete an item	Delete an item revision from a project or from Dimensions CM.
Deliver items	Web client only: Upload files from your work area to Dimensions CM to create new items or update existing items.
Suspend an item	Suspend an item revision to prevent further work on it.
Change item type	Change the type of an item.
Move an item	Move an item revision to a different design part.

For details about working with items, see the following sections:

Web client:	Manage versions
Desktop client:	Manage versions

Item specification

Every item is identified by an item specification: productID:itemID.variant-itemType;revision

The following table describes the specification parameters.

Parameter	Description
productID	The name of the product that contains the item.
itemID	A unique identifier for the item. Depending on your process model rules, the item ID might be automatically generated from the item project file name, or it might be a unique ID typed when the item is created.
variant	The item variant. A variant is an alternative implementation of an item, usually created to meet different standards or customer requirements.
itemType	The item type. For example, a source file might have the type SRC. Item types are defined in the process model.
revision	The revision of the item. The revision can be a number (1 or 1.1) or a mixture of numbers and letters (A1A). If an item is in a named branch, the revision shows the branch name. For example, the revision winnt#1 indicates that this is revision 1 of an item in the winnt branch. The branch name and revision ID are separated by a hash sign (#).

Revision branches

A branch is a chain of revisions that follows its own separate update path.

Branches allow application versions to be developed in parallel. For example, a software application might have separate development branches, one for the next application upgrade and one to rename the application. After finishing your work, you can merge the two branches back into the main development path.

In Dimensions CM, branches are set up at the project level. Any revision that you create or modify in that project follows the project's branch rules.

Note that this does not apply to streams because there can only be one branch in a stream.

If an item in a project has a revision of 1, and the project is not set up to branch, the revision ID of the item is increased as follows: 2, 3, 4.

If the project is set up for an unnamed branch, and the item type uses the standard level numbering scheme, the revision ID of an item whose revision is initially 1 is increased as follows: 1.1.0, 1.1.1, 1.1.2, 1.1.3.

If the project is set up for the named branch upgrade, the revision ID of the item is increased as follows: upgrade#1, upgrade#2, upgrade#3, upgrade#4.

A revision ID may indicate multiple branches. For example, in a project set up for an unnamed branch, an item with the revision ID upgrade#1 is increased as follows: upgrade#1.1.0, upgrade#1.1.1, upgrade#1.1.2.

Item relationships

Items are related to other Dimensions CM objects, such as requests, items, or baselines. Item relationships enable you to trace the creation and release of various components in a product.

An item revision can have the following types of relationships:

Items are owned by a single design part and can be used by other design parts. Item-design part relationships apply to all revisions of an item.
Item revisions are related to the projects/streams, baselines, and releases that include them.
Item revisions are related to the items used to build them or the items built from them. For example, a source file is related to the object file built from it, and an executable file is related to its object files.
Item revisions are related to the earlier revisions that were merged or altered to create them.
Item revisions are related to the requests that affect them, such as bug reports or change requests.

An item revision can participate in user-defined relationships, which are defined in the process model. For example, a design specification document can be related to a source file, or a chapter can be related to a book.

You can view item relationships and, for some relationships, change or unrelate them. For details about relating items to other Dimensions CM objects, see the following topics:

Web client:	Relate and unrelate objects
Desktop client:	Relate and unrelate objects