Example Deployment Scenarios

This section details a number of example deployment scenarios for refactoring changes and explains in detail what occurs for each example. The examples illustrate the following scenarios:

• File rename

• File move

• Folder rename

• Folder move

• File remove

• Folder remove

Deployment Stages Used in the Examples

These examples assume a global stage lifecycle with four stages, "DEV" (Development) "SIT" (System Integration Test) "QA" (Quality Assurance) and "LIVE", each of which have a single attached deployment area, but the same principles would also apply with multiple deployment areas. It is assumed that these deployment areas are attached to the project as Deploy by Default, so that the files are automatically deployed to the area whern they are promoted to the corresponding stage. Filenames are shown in UNIX format (using forward slashes) and the item revision numbers are denoted by a semi-colon followed by the revision number.

The examples assume that the areas involved are associated as Deploy by Default for the project concerned, so that the deployments occur automatically when the changes are promoted. They also assume projects are being used.

Deployment of Regressions

By default, a higher revision of an item file will replace a lower revision if it is deployed to an area, but this behavior is optional. For details, see Deploying Regressions in the Deployment Guide.

Scenario for Renaming a File

When you rename a file in a Dimensions project with attached deployment areas, Dimensions CM will also rename the file on disk in any deployment areas associated with the first stage as default areas. The file will continue to use its original name in areas associated with other stages.

When you promote this change to another stage, the rename will take effect in the deployment areas for that stage. At that time the old file will be removed from those areas and the file will be placed in the areas using the new name.

Example: Content and name change

This example illustrates what will happen if you rename a file in a project and also change its contents. Imagine a Dimensions project contains a file called "src/main.java" and there are various revisions of that file promoted to different stages. The following table shows what is in the main project and each area:

The file names are currently all the same in each area and earlier revisions have progressed further along the stage lifecycle than newer revisions.

A user then refactors the java code and renames "src/main.java" to "src/mainevent.java" (changing its content and name). Only the project and the DEV area are affected so we now have:

If these changes are promoted via a request to “SIT”, the project and area contents would now be:

So as you can see the new revision was placed in "SIT" and the rename took effect.

Example: Name change only

Note that, in the example above when the change was deployed, revision 3 was at SIT and was replaced by the new content (revision 5) in addition to having its name changed. It is not however necessary to change content for a file rename to be deployed. The following example shows a rename without content change being deployed.

The following table shows what is in the main project and each area:

The file names are currently all the same in each area, and earlier revisions have progressed further along the stage lifecycle than newer revisions.

Imagine the user then uses Desktop Client to rename docs/login.html to docs/welcome.html. Only the project and the initial area are affected so we now have:

Next the change is promoted to SIT, the project and area contents would now be:

So as you can see the rename correctly took effect in the SIT area despite the revision already being at the SIT stage.

Scenarios for Moving a File

When you move a file in a Dimensions project with attached deployment areas, Dimensions CM will also move the file on disk in any default deployment areas associated with the first stage. The file will continue to reside in its original location in areas associated with other stages.

When you promote this change to another stage, the move will take effect in the deployment areas for that stage. At that time the file will be removed from the original folder and will be placed in the new folder in areas for the selected stage.

Example: File move

Imagine that a Dimensions CM project contains two folders. One folder is called src and contains two files (src/main.java and src/trace.java). The other folder is called utils and only contains the file logging.java, and there are various revisions of these files promoted to different stages. The following table shows what is in the main project and each area:

The file names and folder locations are currently all the same in each area and earlier revisions have generally progressed further along the stage lifecycle than newer revisions.

Imagine that the user then moves src/trace.java to the utils folder. Only the project and the initial area are affected so we now have:

Next, a request is used to track the move, and that request is promoted to SIT. The project and area contents would now be:

Note that if all of the files in the src folder were moved into the utils folder and promoted to SIT then the empty folder src would remain on disk in your deployment areas. There is no mechanism provided for the removal of empty folders from deployment areas.

Scenarios for Renaming a Folder

When you rename a folder in a Dimensions project with attached deployment areas, Dimensions CM will also rename the folder on disk in any default deployment areas associated with the first stage. The folder will continue to use its original name in areas associated with other stages.

When you use a request to track the rename, and you promote that request to another stage, the rename operation will take effect in the deployment areas for that stage. The files being deployed will then appear in the new folder.

Example: Folder rename

Imagine that a Dimensions CM project contains a single folder called src containing two files (src/main.java and src/trace.java). There are various revisions of these files promoted to different stages. The following table shows what is in the main project and each area:

The file names and folder locations are currently all the same in each area and earlier revisions have generally progressed further along the stage lifecycle than newer revisions.

Imagine that a user then renames src to source. Only the project and the initial area are affected so we now have:

Next, you promote a request referencing the change to the folder name to SIT. The project and area contents would now be:

The src folder in the SIT area now contains no Dimensions CM controlled files.

Scenarios for Moving a Folder

When you move a folder in a Dimensions project with attached deployment areas, Dimensions CM will also move the folder on disk in any default deployment areas associated with the first stage. The folder will continue to use its original location in areas associated with other stages.

When you use a request to track the move, and you promote that request to another stage, the move operation will take effect in the deployment areas for that stage. The files being deployed will then appear in the new folder location.

Example: Folder move

Imagine that a Dimensions project contains two folders. One folder is called src and contains two files (src/main.java and src/trace.java). The other folder is called utils and only contains the file log.java, and there are various revisions of these files promoted to different stages. The following table shows what is in the main project and each area:

The file names and folder locations are currently all the same in each area, and earlier revisions have generally progressed further along the stage lifecycle than newer revisions.

A user then moves the utils folder so that it becomes a child of the src folder. Only the project and the initial area are affected, so we now have:

Next, a request tracking the change, is promoted to SIT, The project and area contents will now be:

The utils folder in the root of the SIT area now contains no Dimensions CM controlled files.

Scenarios for Removing a File

When a file is removed from a Dimensions CM project with attached deployment areas, Dimensions CM will remove the file from any default deployment areas associated with the first stage. The file will continue to exist in areas associated with other stages.

When a file is removed and a request is specified, simply promoting that request to a stage will result in the file being removed from the deployment areas for that stage.

Example: Deploying removal of an item revision

A Dimensions project contains a folder called src containing a file called src/trace.java. Various revisions of the file have been promoted to different stages. The following table shows what is in the main project and each area:

Next, a developer decides to remove trace.java;2, as perhaps it introduced a bug and they wish to quickly back it out. They do this using the Remove Item from Project dialog box in the desktop client, specifying a request R1 in the Track changes with requests(s) field.

At this point, the contents of the project and associated areas will look like this:

Request R1 is then promoted to the SIT stage. Revision 2 of src/trace.java is now removed from SIT:

Example: Deploying removal of an item revision using baselines

As above, a Dimensions project contains a folder called src containing a file called src/trace.java. The following table shows what is in the main project and each area:

Next, a developer decides to remove trace.java;2. They do this against a request and relate trace.java;2 as Affected to mark it as a removal. They create a revised baseline and specify this request in the “Remove” request list. This will create a baseline that no longer contains “trace.java;2”. At this point, the contents of the project and associated areas will look like this:

When this baseline is prompted to SIT, revisions of the items related as “Affected” to the requests specified in the “Remove” list for the revised baseline will be removed from the SIT deployment areas.

The fact that the item revision no longer exists in the project does not affect this. Revision 2 of src/trace.java is now removed from SIT:

Example: Deploying removal of all item revisions using requests

In this example we will see how you can remove all revisions of an item from a deployment area. Imagine a Dimensions project containing a single folder called src containing the file src/trace.java. Various revisions of the file have been promoted to different stages. The following table shows what is in the main project and each area:

Next a developer decides to remove all revisions of trace.java as perhaps its functionality was moved into another file. They specify a request when removing both the revisions of trace.java using the Remove Item from Project dialog box in the desktop client.

At this point in time the project and area contents will look as follows:

When the request is promoted to SIT, the project and area contents will now look as follows:

All revisions of src/trace.java have now been removed from "SIT".

Example: Deploying removal of all item revisions using baselines

Now we will see how you can remove all revisions of an item from a deployment area when the deployment method for the project is baseline. Imagine the same example of a Dimensions project containing a single folder called src containing the file src/trace.java. Various revisions of the file have been deployed to different stages using baselines. The following table shows what is in the main project and each area:

A developer decides to completely remove all revisions of trace.java. As described above, if you are using baseline deployment,  removals are only deployed if they are related as "Affected" to a request used in the "Remove" list for a revise baseline operation, and that baseline is promoted. So the developer relates both revision 1 and 2 of src/trace.java as "Affected" against a request, and creates a revised baseline specifying that request in the "Remove" request list. This will create a baseline that no longer contains trace.java. They also remove both revisions of the item from the project.

At this point in time the project and area contents will look as follows:

When the baseline is promoted to SIT, the project and area contents will now look as follows:

All revisions of src/trace.java have now been removed from "SIT".

Folder Removal

If the developer specifies a request when deleting an empty folder, then when that request is promoted to a stage, the empty folder will be deleted from the corresponding areas.

Rollback of Deployed Objects to an Earlier Stage

The Global Stage Lifecycle (GSL) allows for transitions back to earlier stages in the lifecycle. A version of an area can be rolled back provided there are no subsequent versions of the area that depend on any changed made by the version being rolled back. Refactoring changes must be demoted in the reverse order to which they were deployed up.

Scenarios for Demoting

If you are demoting a request deployment, then file and folder removes will revert to their old values when the request is demoted.

Example: Demoting a file rename

This example illustrates what will happen if you demote a previously promoted file rename.

The following table shows the filename and revisions initially in the main project and each area. The filename is the same, and earlier revisions have progressed farther along the stage lifecycle with later revisions:

The user uses the desktop client to rename the file in the project to welcome.html against the default request R1, and the filename is changed in the project and the initial stage:

This change is then deployed to SIT by promoting request R1, and the project and area contents become:

So the file is now renamed in the SIT area.

Now, at this point testing occurs at the SIT stage, and the team realizes that the file rename needs to be backed out from the SIT stage. The team leader demotes request R1 back to DEV, and the project and area contents become again:

So the file rename was reverted in the SIT area.