Phases in the View Compare/Merge Process

View Compare/Merge provides consistent view compare/merge features across all client platforms. It supports refactoring and directionality. View Compare/Merge is optimized for distributed teams, and is oriented around merge tasks to facilitate the way you really work. It also allows the review and commit phases to be divided across time.

All sessions follow the same basic process which is divided into the following phases:

  1. Definition
  2. Comparison
  3. Review
  4. Save and Restore
  5. Commit

Definition Phase

The View Compare/Merge parameters are specified for the compare phase. The session is defined in terms of its merge type, the source view (and snapshot), the target view, the source scope, and various options.

  • In the StarTeam Cross-Platform Client, a session is started from a View Compare/Merge menu option which is available in several places, and which launches the View Compare/Merge Wizard. The context from which the wizard is launched affects the definition of the session.
  • In the VCMUtility, the session is defined by command-line arguments and/or an options file.
  • Both the StarTeam Cross-Platform Client and VCMUtility provide a variety of ways to define the source scope items. The source scope can be:
    • The file revisions linked to one or more process items (and optionally the process items themselves).
    • The items attached to a revision label.
    • Items of specific types that reside in selected folders.
    • A set of explicitly selected items; and items of selected types in the entire view.

The definition phase is where you define the process for the comparison. In this phase, you can:

  • Specify the view merge type.
  • Specify the source view, item(s), target view, and options.
  • Specify the type of items to include.

Comparison Phase

The Comparison phase is where the comparison takes place. The comparison takes place automatically when you finish the wizard before the View Compare/Merge opens in the StarTeam Cross-Platform Client.

Once a session starts, View Compare/Merge first performs the Comparison phase.

  • “In scope” source items are matched to corresponding items in the target view. View Compare/Merge detects both simple changes (items that are new, modified, or deleted in one or both views) and more complex changes (items that have been moved, renamed, modified-and-moved, and so on.)
  • For an item that exists in both the source and target view, it determines if either item or both have changed since the last time they were merged.
  • For each difference found, it defines an item difference that specifies the source and/or target item (sometimes there is only one of these) as well as a default action. The action specifies what the session will do about the item difference. Many actions are possible including ignore, move, merge, delete, reverse share, move and merge, and so on.

Review Phase

After the comparison phase has completed, the results can be reviewed, adjusted, and validated before the session is committed. The review phase is where you analyze your comparison and make any necessary adjustments.

In the Review phase of a session, you can

  • Preview what the target view would look like if the session was committed in its current state. The StarTeam Cross-Platform Client provides this preview as a Test Perspective. The VCMUtility provides a CheckoutPreview option that allows you to check out files from the preview.
  • Generate a difference report in both the StarTeam Cross-Platform Client and VCMUtility that summarizes all item differences and their current actions.
  • Resolve differences requiring user input, and manually merge file contents and property values when there are conflicts. Actions are considered resolved if no user input is required to continue. However, unresolved actions such as differences with merge conflicts, require user input. The session cannot be committed without user attention. As a best practice, all actions should be reviewed and adjusted if necessary.
  • Choose from multiple possible actions to resolve differences where applicable. For example, for an item in a merge state (modified in both views since the last compare), you could choose to overwrite the target item to match the source item instead of choosing to merge the two.
  • Check out files to working folders, perform a build, and run tests on the simulated merge.
  • Define properties of the change package that will be created when the session is saved or committed such as its name and description.

Save and Restore Phase

Optionally, at any time after the compare phase, you can save the session and restore it later. By default, a session is saved as a change package in the target view identified by the session. A session can also be saved as a local session file or exported as a self-contained exchange file. All three ways of saving a session allow it to be restored later. Restoring a session “resumes” the session at the same point at which it was saved.

  • When a session is saved as a change package, you can copy a URL for it to the clipboard and paste it into an e-mail, for example, so others use the URL to open the change package.
  • A session saved as a Session file (.vcms file extension) is a shortcut that can only be used to restore the session on the same computer. This is because temporary files are saved on the workstation required to resume the session.
  • A session exported as an Exchange file (.vcmx file extension) is a self-contained “change package” file that can be copied to another computer, e-mailed, checked into StarTeam or added to a change request as an attachment, and so on. Others can then restore, review, and even commit the session.

Change packages are the preferred method for saving and restoring sessions.

Commit Phase

In the commit phase, View Compare/Merge applies changes to the target view based on the decisions made during the compare and review phases, and records the changes in the StarTeam repository as a change package.

Based on session options, various labels can be automatically created that document what changed in the target view. View labels can be created that provide a snapshot of the target view before and/or after the updates were applied. Revision labels can be created that are attached to target view items affected by the session before and/or after the updates were applied.

View Compare/Merge can also generate a post-commit update report, which enumerates exactly what was changed by the change session.

Parent topic: View Compare/Merge Process