Revise and merge baselines

You can create a revised release baseline, or merge two release baselines into one.

Note: Use a release baseline to create a revised or merged baseline. You cannot revise and merge baselines using design or archive baselines. For details about baseline types, see Revise and merge baselines.

Revise baselines

To create a revised baseline, you apply requests to a previous baseline. Applying requests affects the original baseline based on the relationship of the item revision to the request.

You can use the following request groups to revise a baseline:

Request Description
Update baseline using

Requests used to update the baseline with item revisions.

When you create a revised baseline using the Update baseline using list, modifications to the original baseline, based on the relationship of the item revisions to the requests, are made as follows:

  • Requests with item revisions that are related as Affected only will have no effect on the new baseline.

  • Requests with item revisions that are related to them as Affected and In Response To will have any previous versions of those same items already in the original baseline replaced with the In Response To revision, regardless of whether or not the revision of the item in the original baseline matches the revision related to the request as Affected.

  • Requests with item revisions that are related as Affected and In Response To where the Item ID of the In Response To item is not already in the original baseline at any revision will have the In Response To revision added to the revised baseline.

  • Requests with In Response To revisions only will have the In Response To revisions added to the baseline.

  • If a request relates to refactoring changes, those changes are processed as described in Project structure changes.

Remove from baseline

Requests used to remove item revisions from the baseline.

When you create a revised baseline using the Remove from baseline list, any item revisions in the original baseline that are related as Affected to the requests will be removed from the new baseline.

If two or more item revisions are on different branches, Dimensions CM issues a warning and continues without changing the revision of that item in the baseline.

For example, if you create a new baseline for a maintenance release from the main development branch, it may contain unwanted features and untested code. However, if you revise a previous release baseline, the only changes introduced are those contained in the requests included in the baseline.

Every revised baseline has only one revision of any item, so it can be used like any other release baseline, for example, to create a test or release configuration of the product.

You can also use a revised or merged baseline to create another revised baseline. Because the contents of this baseline are no longer determined directly by the rules of a baseline template, its template ID is REVISED.

Back to top

Project structure changes

When you create a revised baseline, it includes change information for all project structure or refactoring changes related to the specified requests.

When you perform actions that involve refactoring, such as renaming a project folder, or exporting an item to the project, and you specify a request in the Track changes with request(s) field, those changes will be recorded against that request.

If you specify those requests in the Update baseline using list, the changes will be applied to the revised baseline.

Recorded project structure changes

When project structure change control is enabled, the following changes to project structure are recorded against change requests:

Change Description
Item addition and removal

An item revision is added or removed from a project. The change is recorded in one of the following:

  • The change request that lead to the structure change.

  • The default change request.

Item rename An item is renamed or moved in the project structure.
Directory creation, deletion, and rename A directory is created, deleted, or renamed in the project structure.

How structure change requests are used

When you create a revised baseline, the new baseline will include all the structural changes tracked by the specified requests.

The structural changes will only be applied if they relate to the project whose context matches that within which the baseline is being revised. Structural changes outside of this context will be ignored.

How the structure changes are interpreted

When you create a revised baseline, the Create Revised Baseline operation interprets different types of structure changes in the following ways:

  • Item additions related to update requests are interpreted as new candidate items to be added to the baseline.

  • Item and directory renames related to update requests are interpreted as candidate changes to the baseline file/folder structure.

  • Item removals related to update or remove requests are interpreted as candidates for removal from the new baseline.

  • Directory removals related to update or remove requests are interpreted as candidate changes to the baseline structure.

For details about revised baselines, see Baseline categories.

Structure changes behavior when creating revised baselines:

  • The operation ignores directory or item removals if the items or directories were not in the original baseline or have not since been added in the context of a structure change.

  • All structure changes are performed in their original sequence to ensure integrity is maintained when item and directory renames are interleaved.

  • If there was a rename or removal change to a directory path, the operation avoids renaming or removing the wrong directory by ensuring that there have been no directory additions or renames to the same path since the baseline was created.

    For example, if:

    • The original baseline included the folder /source.

    • The original /source folder has since been deleted.

    • A new folder named /source has been added, with different content.

    • The new /source folder was renamed to /files.

    Then the Create Revised Baseline operation detects that the original /source folder is not the same as the new /source folder, and fails with an error.

Back to top

Merge baselines

A merged baseline is created by selecting a top level design part, and specifying two or more existing baselines from which item revisions are to be included. Each input baseline must be either a release baseline or an earlier merged or revised baseline. All the baselines must reference the same product that will be specified for the new baseline.

The baselines in a list are considered in the order specified in that list. Every item in each baseline is checked and ignored if:

  • It is not in the new baseline's project or design part structure.

  • Any revision of the same item has already been added to the new baseline.

If these checks are passed, the item revision is added to the new baseline. This continues until all items in all the baselines in the list have been dealt with.

This processing rule means that, for any item in the merged baseline, the revision added will be the one found in the first baseline in the list that contains that item. Therefore, to obtain a merged baseline with satisfactory contents, you would normally list the input baselines by creation date, in ascending order (the most recent baselines first and the oldest last).

A merged baseline typically has the same scope, or list of design parts, as the baselines used to create it. However, if you select a design part that is different from the source baselines, items that are in the source baselines that are not owned by the design part of the merged baseline are not included in the new baseline.

Every merged baseline has no more than one revision of any item, so it can be used like any other release baseline. For example, to create a test or release configuration of the product.

You can also use a revised or merged baseline to create another merged baseline. Because the contents of such a baseline are no longer determined directly by the rules of a baseline template, its template ID is MERGED.

For details about merging baselines, see the CMB – Create Merged Baseline command in the Command-line reference.

See also: