January 19, 2011

Merging Between Branches in Surround SCM

Surround SCM
If you use a robust software configuration management system like Surround SCM, chances are you are using branches. Changes made in one branch usually need to make it to another branch. Surround SCM offers different ways to merge these changes.

Finding the differences

Before you start merging changes between branches, you may want to check for differences between the branches first. To view differences at the branch level, you can use Branch Differences. This feature is available from the Branch menu. Just make sure you are in one of the branches you want to compare. [caption id="attachment_6899" align="aligncenter" width="518" caption="Branch Differences"]Branch Differences[/caption] In the Branch Differences window, select a file and then click on Differences. This will show the differences at the file level. If you know which file you want to view differences for, you can select Differences... from the Activities menu. Under the Advanced options you can select the file in another branch. [caption id="attachment_6903" align="aligncenter" width="340" caption="Advanced File Differences"]Advanced File Differences[/caption]

Promote

Promote allows you to take all the changes in a file up to a certain point and merge them with a parent branch. You can select up to which point in time to look for changes with the following options:
  • Latest version: Take all changes and merge them with the parent branch.
  • Label: Take all changes up to the version associated with the selected label and merge them with the parent branch.
  • Timestamp: Take all changes up to the version associated with the selected timestamp and merge them with the parent branch.
  • State: Take all changes up to the version with the selected state and merge them with the parent branch. This is a great way to ensure that only files that have been "approved" are promoted.

[caption id="attachment_6906" align="aligncenter" width="426" caption="Changes are normally promoted to parent branches"]Changes are normally promoted to parent branches[/caption]

When you promote changes to the parent branch, Surround SCM tracks the last set of changes which were promoted. This makes future merges easier because Surround SCM only needs to worry about changes since the last time you did a promote. Also, this reduces the chances of a merge conflict and having to manually merge changes. Surround SCM gives you the option to promote changes to the immediate parent or to another branch higher in the hierarchy (ancestor branches). Organize your branch structure so that you are always promoting changes to the immediate parent, and only promote to ancestor branches in rare occasions.

Rebase

Rebase allows you to take changes in the immediate parent and merge them with the current branch. You can choose to take changes up to a certain point just like promotes:

  • Latest version: Take all changes from the parent branch and merge them with the current branch.
  • Label: Take changes up to the version associated with the selected label in the parent branch and merge them with the current branch.
  • Timestamp: Take changes up to the version that the file had at the timestamp selected in the parent branch and merge them with the current branch.
  • State: Take changes up to the last version in the selected state in the parent branch and merge them with the current branch.

[caption id="attachment_6909" align="aligncenter" width="426" caption="Changes can only be rebased into child branches"]Changes can only be rebased into child branches[/caption]

Duplicate Changes

Duplicate Changes is different from promotes and rebases in three ways:
  • Changes can be merged regardless of hierarchy.
  • Differences between changes are merged instead of "all changes up to a certain point".
  • You can duplicate changes based on Defect, Changelist, Label, or specific versions.

[caption id="attachment_6915" align="aligncenter" width="372" caption="Changes can be duplicated to any branch"]Changes can be duplicated to any branch[/caption]

Duplicate Changes versus Promote and Rebase

When we first added the Duplicate Changes feature, I thought this would become the feature of choice for merging changes between branches. However, duplicating changes is not the same as promote and rebase. Remember that promote and rebase take all changes up to the time stamp that you select, but duplicate changes only takes changes between two versions.

So promote and rebase are the preferred method for keeping branches in sync with all changes. Duplicate changes is the preferred method to take a specific change, usually associated with a label, defect or changeslist, and copy it to another branch.

Merge Tracking

Surround SCM keeps track of the merging that takes place via promotes, rebases and duplicate changes.

Under Tools > Track Changes..., you are able to track changes that have been merged.

[caption id="attachment_6922" align="aligncenter" width="451" caption="Tracking changes associated with a label"]Tracking changes associated with a label[/caption]

In the previous screenshot, the Track Changes feature is used to verify where Change #35 was made to the mainline branch. Track Changes makes it easy to know if a change has made it to appropriate branches or if it was made in the wrong branch.

Another useful feature that allows you to track merging across branches is the Graphical History feature in Surround SCM. For more information about this feature, check out this video.