November 10, 2009

MergeByDefect

Surround SCM

Works with Surround SCM 2010 and later

Will not work with Surround SCM 2009 and earlier

MergeByDefect is an application that takes advantage of Surround SCM's plugin architecture and API to give the user a tool to merge changes related to a TestTrack defect with the same file on another branch. This application was originally posted as SSCM Bug Merge, which required a lot of manual input. MergeByDefect takes advantage of environment variables made available through the plugin architecture and the Surround SCM API to eliminate manual input. NOTE: Seapine does not support sample applications and tools [toc] Just like the original, MergeByDefect uses GNU Patch to handle the actual merging. You will have to download this tool separately. This means that this tool is at the mercy of Patch. Any merges that Patch can not handle will have be done manually. If you know of another merge tool that works in a similar fashion, but yields better results, please share.

Use Case

MergeByDefect should be configured to be available from a file's context menu only. Ideally, it should only be available when a single file is selected. For help on setting up the plug in please refer to the Surround SCM Custom Client Menus article. When MergeByDefect opens, it will show the currently selected file (full path) and branch.

MergeByDefect GUI

The user then can select the proper defect number and browse for the destination branch. In the Branch Browse window, the user will only see the mainline branch and baseline branches.

Branch Browser

The user selects the destination branch and clicks OK. The Browse branch window closes and goes back to the main window.

MergeByDefect GUI before merge

The user gets one last chance to review the information. Once ready for merging, the user clicks on the "Merge" button. Only a successful merge is checked in on the destination branch.

App Details/Flow

When MergeByDefect is launched, it gathers information about the file, including the branch, repository path and file name. This information is gathered from the environment variables made available by the plugin architecture. Since MergeByDefect now knows the branch, repository and file name, it is able to check the file's properties using the Surround SCM API to ensure that it is not a binary file, since these can not be merged. It also checks if the file is UTF-8 or UTF-16. If it is, the user is prompted with a warning that Patch may not be able to handle certain unicode encodings. The user has the option to stop or continue with the merge. NOTE: In order for MergeByDefect to check the file, it requires that you have the correct repository selected in the client. If you have files listed recursively, you may not have the right repository selected. MergeByDefect queries the file's history to see if any Attach To Defect events have taken place. If it does not find any, it gives the user an error message and MergeByDefect closes. If it does find attach to defect events for the file, it parses out the comments to extract the defect number. It populates the Defect Number drop down list with the defect number(s) and associated version.

List of defects and versions

The Destination Branch text box is read only and will only be populated by browsing the Surround SCM repository tree. The user clicks on the browse button and this opens the branch browser. To keep things simple, this Window will display a branch tree with only the mainline and baseline branches. Snapshot and workspaces are not displayed at this time. When the user clicks on the Merge button, the following actions take place:
  • MergeByDefect calls the Surround SCM CLI (command line interface) differences report command. This generates a difference report between the version associated with the defect and the previous version. The report is generated in Unified format. Please refer to the Troubleshooting section for more details on this.
  • The Difference report is saved as "patch.txt".
  • MergeByDefect uses the Surround SCM API to check out the file on the destination branch. If it can't check out the file (maybe it is exclusively checked out by someone else), an error is returned to the user.
  • MergeByDefect calls Patch and passes the checked out file and the difference file for patching. Please refer to the Troubleshooting section for more details on this.
  • If the patch is successful, the resultant file is checked in. Otherwise, the error is returned to the user and using the Surround SCM API, MergeByDefect undoes the check out.

Configuration

Configuration File

MergeByDefect reads the information needed to connect to the Surround SCM server from a configuration file called "CMConfig.xml". This file must reside on the same directory as the MergeByDefect.exe file. A sample file is provided with the Download. The file must have the following information:
  • UserName - User name to connect to Surround SCM
  • Password - Password for the above user
  • SCMServerAddress - Surround SCM IP address or host name
  • SCMServerPort - Port of the above server
  • SSCMLocation - Location of the Surround SCM CLI (sscm.exe). Used to run the difference report
  • PatchLocation - Location of Patch.exe (must be downloaded separately).
  • WorkDir - Temporary directory for MergeByDefect to do its work. MergeByDefect will not clean this directory up, so keep an eye on it so it does not get too big.
The file must have the following structure:
<CMData>
	<UserName></UserName>
	<Password></Password>
	<SCMServerAddress></SCMServerAddress>
        <SCMServerPort></SCMServerPort>
        <SSCMLocation></SSCMLocation>
	<PatchLocation></PatchLocation>
	<WorkDir></WorkDir>
</CMData>

Building a custom menu in Surround SCM client

Please refer to the Surround SCM Custom Client Menus article on how to configure access to MergeByDefect from the Surround SCM client. This is written to be used as a plug in and therefore will not work outside of Surround SCM. Ideally MergeByDefect should be available from the file's context menu.

Download

You can download the entire Visual Studio project from here. The top level folder that contains the solution file also contains the icons used on both forms. They are provided as .ico and .png file formats. The .png formats are provided for use when configuring the Surround SCM custom menu.

Troubleshooting merge issues

As mentioned above, all merging is performed by calling Patch. If merges are failing or are not doing what you expect them to do, you will have to refer to Patch's documentation. The general syntax used in this application is: patch.exe -u -t -N <fileToPatch> <diff file> To get a list of all options available and a description, type the following on the command line: patch --help Depending on your needs you may need to add and/or remove some of the options. You may have to resort to running the patch command manually and play around with the various settings to see if any of them make any difference. Keep in mind that MergeByDefect is calling the Surround SCM Command line to generate the diff file. The syntax being used is: sscm dr <file name> -b<branch where file is> -p<repository where file is> -o<temp dir path>patch.txt -v<version associated with defect> By default, the diff file is generated using the Unified format. You may want to try setting the -l option and set the diff format to Context. You will also need to change the Patch command. Lastly, as noted in the Configuration section, the directory that MergeByDefect uses to place the files is not cleaned up, so you can go there after a failed merge and look at the differences report file (patch.exe) and the file Patch tried to merge. You can try to run patch manually and try the various options to see if that solves the issue. Note: Seapine does not provide support for sample scripts.