Version control

This topic describes how to work with entities of projects in Web Client that have version control enabled.

Version control overview

If a project has version control enabled, you can create and manage entities while maintaining all previous versions of these entities.

Version control is available for the Requirements and Test Plan modules.

Version control use examples

Version control helps in the following scenarios:

Scenario	Example
Monitor entity changes and compare versions	Kelly, a product manager, uses version control to identify discrepancies between current product requirements and the original agreed-upon versions, allowing her to understand changes in development.
Restore an earlier version	Michael, a QA tester, encounters a significant issue with a new build of a banking application. When the development team rolls back to a previous build, he reverts to earlier versions of his tests to continue his work effectively.
Lock entities for editing	Robert, a business analyst, needs to update application requirements over several days. To prevent others from making changes during this time, he checks out the requirements for editing, ensuring his work remains uninterrupted.

Prerequisites

Prepare for the following before working with version control.

Prerequisite	Details
Enable version control	Verify that version control is enabled for your project. For details, see Enable or disable version control for a project.
Specify versioned and non-versioned fields	When your project has version control enabled, you can disable and enable version control at the entity field level. By default, it is enabled for most fields. Versioned fields: Fields that have version control enabled are versioned fields. Values of these fields are saved in each earlier version. Non-versioned fields: Fields that do not have version control enabled are non-versioned fields. Values of these fields are not saved in earlier versions. For details about enabling version control for entity fields, see Customize project entities.

Prerequisite

Details

Enable version control

Verify that version control is enabled for your project.

For details, see Enable or disable version control for a project.

Specify versioned and non-versioned fields

When your project has version control enabled, you can disable and enable version control at the entity field level. By default, it is enabled for most fields.

Versioned fields: Fields that have version control enabled are versioned fields. Values of these fields are saved in each earlier version.

Non-versioned fields: Fields that do not have version control enabled are non-versioned fields. Values of these fields are not saved in earlier versions.

For details about enabling version control for entity fields, see Customize project entities.

Check out an entity

Check out an entity before you edit it. After it is checked out, it is locked and cannot be edited by other users.

To check out an entity:

When you create an entity, it is checked out automatically.

To check out an existing entity, do one of the following:

Action	Details
Automatic checkout	Start editing the entity. In the Check Out window, enter the change comments and click OK. If you want automatic checkouts without showing this window, do either of the following: Select the Don't show this again option in the Check Out window. From the module toolbar, clear Versions > Warn Before Check Out.
Manual checkout	From the entity tree, select the entity. To select multiple entities, use the SHIFT key. From the module toolbar, click the Check Out button . To check out a single entity, you can also select More Actions next to the entity and select the Check Out button . In the Check Out window, enter the change comments and click OK.

Action

Details

Automatic checkout

Start editing the entity.
In the Check Out window, enter the change comments and click OK.

If you want automatic checkouts without showing this window, do either of the following:

Select the Don't show this again option in the Check Out window.
From the module toolbar, clear Versions > Warn Before Check Out.

Manual checkout

From the entity tree, select the entity.

To select multiple entities, use the SHIFT key.
From the module toolbar, click the Check Out button .

To check out a single entity, you can also select More Actions next to the entity and select the Check Out button .
In the Check Out window, enter the change comments and click OK.

After an entity is checked out, it is indicated by a lock.

If it is checked out by you, the entity is indicated by an open lock icon.
If it is checked out by another user, the entity is indicated by a lock icon , and the entity name is followed by (checked out by <username>).

You can also check out an earlier version to revert back to that version. For details, see Work with earlier versions.

Undo a checkout

After an entity is checked out, you can undo the checkout to cancel the changes you made. The entity is unlocked when you undo the checkout.

Note: When you undo a checkout, changes made to non-versioned fields are not cancelled and their new values remain.

To undo a checkout that is done by you, select the entity, and from the module toolbar, select Versions > Undo Check Out.

To undo a checkout that is done by other users, you must have Undo Checkouts permission. For details, see Set group permissions.

Check in an entity

When you finish updating an entity, check in the entity to create a new version and unlock the entity.

To check in an entity:

From the entity tree, select the entity.

To select multiple entities, use the SHIFT key.
From the module toolbar, click the Check In button .

To check in a single entity, you can also select More Actions next to the entity and select the Check In button .
In the Check In window, enter the change comments and click OK.

Keep checked out. Enables you to check in the changes you made to the entity but still keep the entity checked out.
- If you select this option, the entity changes are checked in and a new version is added, but the entity is still checked out.
- If you clear this option, the entity is checked in and unlocked.

Copy, move, or delete version-controlled entities

Consider the following guidelines when copying, moving, or deleting version-controlled entities.

For a single entity

Action	Details
Copy/Paste	The entity must meet either of the following requirements: It is checked in. It is checked out by another user. The current checked-in version is copied, and the entity is automatically checked in after being pasted.
Move (Cut/Paste)	The entity must meet either of the following requirements: It is checked in. It is checked out by you. The entity remains checked out after being moved.
Delete	The entity must meet either of the following requirements: It is checked in. It is checked out by you.

Action

Details

Copy/Paste

The entity must meet either of the following requirements:

It is checked in.
It is checked out by another user.

The current checked-in version is copied, and the entity is automatically checked in after being pasted.

Move (Cut/Paste)

The entity must meet either of the following requirements:

It is checked in.

It is checked out by you.

The entity remains checked out after being moved.

Delete

The entity must meet either of the following requirements:

It is checked in.

It is checked out by you.

For a folder or multi-selected entities

Action	Details
Copy/Paste	Either of the following requirements should be met: All the entities are checked in. None of the entities is checked out by you. The current checked-in version of each entity is copied. The entities are automatically checked in after being pasted.
Move (Cut/Paste)	Either of the following requirements should be met: All the entities are checked in. All the entities are checked out by you. They remain checked out after being moved.
Delete	Either of the following requirements should be met: All the entities are checked in. All the entities are checked out by you.

Action

Details

Copy/Paste

Either of the following requirements should be met:

All the entities are checked in.
None of the entities is checked out by you.

The current checked-in version of each entity is copied. The entities are automatically checked in after being pasted.

Move (Cut/Paste)

Either of the following requirements should be met:

All the entities are checked in.

All the entities are checked out by you.

They remain checked out after being moved.

Delete

Either of the following requirements should be met:

All the entities are checked in.
All the entities are checked out by you.

Work with earlier versions

All earlier versions of an entity are maintained. You can view an earlier version or revert back to an earlier version and continue working from that version.

To view an earlier version:

Select the target entity and click the History > Versions tab.

All versions are listed, with the currently checked-out version indicated by an arrow .
Select the version you want to view and click Details.

The entity details displayed are read-only. Values of non-versioned fields are not saved and they are filled with <Non-versioned Field>.

Note: When you view an earlier version of a test, only the Details tab of the test is displayed.

To revert back to an earlier version:

Select the target entity and click the History > Versions tab.
Select the version you want to restore and click Details to make sure it is the target version.
Click Check Out.

The entity is reverted back to this version. All changes made after this version are discarded. Non-versioned fields are filled with the values in the latest checked-in version.