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 compare current requirements with the original agreed versions and understand development changes.
Restore an earlier version	Michael, a QA tester, hits a major issue in a new banking application build. When the team rolls back, he restores earlier test versions to continue working.
Lock entities for editing	Robert, a business analyst, updates requirements over several days. To prevent concurrent edits, he checks out the requirements so he can work without interruptions.

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. The version number assigned to a new entity is 1.

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 your checkout:

Select the entity.
From the module toolbar, select Versions > Undo Check Out.

To undo a checkout that is done by someone else, 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.

View checked out entities

You can view all entities in the current module that you have checked out.

To view checked out entities:

From a module menu bar, select Versions > Pending Check In.
Click the View action to edit the entity.
To select multiple entities, press the CTRL key and select the entities.
Check in or undo the checkout for the selected entities.

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.

Compare two versions of an entity

Available for: Version 26.1 P1 and later

You can compare two versions of an entity.

To compare entities:

Select an entity and click the History > Versions tab.
Select two versions and click Compare.

The Changes column shows the status of changes.

Tip: Use the View dropdown menu to show all fields, or only changed or unchanged fields.

Non-versioned fields

Some fields are not versioned and updates to those fields are not tracked in version history.

Consider the following when working with non-versioned fields in a version control enabled project:

Action	Result
Undo a checkout	Any changes you made to non-versioned fields while the entity was checked out are not cancelled and the new values remain.
Check out a previous version	The value of a non-versioned field is the value in the currently checked in version.
View and compare previous versions	Non-versioned fields are displayed with the value Non-versioned Field. When viewing and comparing previous versions, pages for which version control data is not stored are not displayed.

Action

Result

Undo a checkout

Any changes you made to non-versioned fields while the entity was checked out are not cancelled and the new values remain.

Check out a previous version

The value of a non-versioned field is the value in the currently checked in version.

View and compare previous versions

Non-versioned fields are displayed with the value Non-versioned Field.

When viewing and comparing previous versions, pages for which version control data is not stored are not displayed.