Deploy refactoring changes

Use Dimensions CM requests to deploy refactoring changes.

Refactoring rules and behaviors

Refactoring occurs when there are modifications in the project/stream structure that change names or locations of files or folders, for example, exporting an item to a project, deleting an item, or moving a subfolder from one parent folder to another.

The following changes in the Dimensions CM web client, desktop client, or dmcli client result in refactoring:

  • Renaming a file or folder.

  • Moving a file or folder.

  • Deleting a file or folder.

When you make these changes, they happen automatically only in the project/stream in which you perform the changes, and in any areas associated with the project's initial deployment stage that are defined as Deploy by Default.

To deploy the changes to the deployment areas for other stages in the Global Stage Lifecycle (GSL), you need to take additional action.

Rules and guidelines:

  • If you have refactoring changes, you must deploy them using a request and not a baseline.

  • If you deploy refactoring changes out of sequence, the deployment fails.

  • Always refactor using a new request that is not related to any other changes. Otherwise, when you need to deploy the refactored changes (because another change is dependent on it), you may jnot be able to deploy the refactoring request because the other changes are related to it.

Back to top

Request-driven refactoring

Using Dimensions CM requests to track refactoring changes is the recommended method of ensuring that these changes are reflected in the appropriate deployment areas. Baselines cannot be used to deploy refactoring changes.

When you perform actions that result in refactoring, such as exporting a file to a project or moving a project folder, those changes are recorded against the request ID you supplied when you performed that action. When you subsequently promote one of these requests to another stage in the GSL and deploy it, the refactoring changes tracked against that request are also applied to the deployment areas associated with the new stage.


  • For projects, set this project option: Request required to refactor

    This means that you are required to provide one or more request IDs when you perform an action that results in refactoring, such as exporting an item or renaming a project folder. Otherwise the action is not completed.

  • For streams, set this option: Valid request must be specified when delivering changes

    Refactoring changes take place in the work area and are then delivered to the stream. Using the request your specified when delivering changes means that you can use the request to deploy any refactoring changes that occurred.

Request-driven refactoring example:

Suppose a developer needs to move the foo.c file from the src folder to the utils folder.

The project uses the GSL consisting of these stages:


To move the foo.c file, the developer performs the following steps:

  1. In the Dimensions CM desktop client, in the Move dialog box, the developer moves the item in the project, and enters a request, R1, in the Track changes with request(s) field.

    The project and the areas associated with the DEV stage now contain the item file:


    Whereas the deployment areas for stages SIT, QA, and LIVE still contain the file:


  1. The developer then wants to deploy this change to SIT. He therefore promotes and deploys the request R1 to the SIT stage.

    The deployment areas for SIT now contain the file utils/foo.c. The deployment areas for QA and LIVE, however, still contain the file src/foo.c.

  2. When the change is ready to be deployed to QA and LIVE, the request R1 is subsequently promoted and deployed to those stages.

Request-driven refactoring has the advantage of supporting all the types of refactoring: removing, moving, or renaming of folders or files. It also allows demoting back down the GSL.

Note: During request-driven deployment, you must deploy refactoring changes up in the order in which the refactoring changes were carried out. For example, if you add the file foo.c to the project, and then rename it to bar.c, you need to promote the file foo.c to a particular stage before the rename can be promoted to that stage.

Back to top

See also: