SCC File Diff Report Utility

From Seapine Labs

Contents 1 Situation 2 Solution 3 Requirements 4 Disclaimers 5 The Application 5.1 Download 5.2 Use case 5.3 How to use it 5.4 Known issues 5.5 Improvements/enhancements 6 Comments/Suggestions

[edit] Situation

You are about to put a build or a release together, and you would like to know not only which files have changed, but what in the files has changed.

You want a list of all issues addressed in this release, all source code files associated with them and what actually was changed in these files in order to address the issues.

[edit] Solution

Previously I had posted an example on this wiki on how to get files for a build. This example showed how you could use the TestTrack automation rules and a script to allow you to retrieve the Source Code Control versions of the files associated with defects and/or change request associated with that build.

Building on that concept, this example builds the list of files and then runs a diff command and includes this in an HTML table.

The result is a table that contains the defect number, the defect summary, the SCC file(s) included in that defect and the difference information between the version associated with the defect and the previous version.

Figure 1 below shows a sample output of the report:

While TestTrack's powerful reports are able to give you a list of defects and all source code files associated with them, it will not give you the difference information. This last piece of information I felt could be very powerful for anybody who needs to review what is about to be included in the next build/release.

[edit] Requirements

For this example to be useful, please note the following:

• You must be running version 2008.1.1 of Surround SCM and TestTrack. Older versions may work, as long as the SOAP methods and the command line interface commands are not different.

• You must have Surround SCM as the Source Code Control tool integrated with TestTrack and also we able to associate "Fixed Revisions" with these files. This is achieved when you check in a file from TestTrack or perform the fix event when you attach a check in event to a defect from Surround SCM.

• You must have the SOAP interface working properly since the application uses it to retrieve the list of files and defect information.

• You must have the Surround SCM Command Line Interface (CLI) installed on the same machine in the default installation directory. The applicaiton calls the sscm.exe file and it expects it be in the default installtion directory (C:\Program Files\Seapine\Surround SCM\).

• You must have at least version 2.0 of the .NET framework installed.

• If you wish to make changes to this application, you will need Visual Studio 2005 or later.

• There may be other requirements that have not been identified as of the time of this writing.

[edit] Disclaimers

This is provided as an example only. While this does work in my environment, it may not work in yours.

While I made this a GUI application to allow you to enter all information that will be different, there may still be a need for some adjustments.

This is not provided as an add-on to TestTrack or Surround SCM. You are welcomed to use it in your environment, but it is your responsibility to make any changes for this to work in your environment.

If you use another Source Control tool you will have to make changes to use that tool's command line interface or API and may need to change the GUI to take the parameters needed by this interface. You probably will also have to change the code that parses the SCC file associated with the defect.

[edit] The Application

[edit] Download

You can download the Visual Studio Project from here. In the \bin\debug folder you will find the debug binary which you may be able to use.

[edit] Use case

The application will retrieve those defects that pass the filter you select. The idea is that you will select a filter that identifies those defects that are included in the next build/release.

A suggestion for such filter could be one that looks at the version in the fix event dialog. When a user performs a "fix" in TestTrack, he or she would select a version from the fix event dialog. This would be the version of the build/release to included in. You could also add a custom field to the fix event, one for the release, and one for the build, since your next release may be a result of several builds.

Also, you probably would need to ensure that users are attaching their check ins to defects and performing the "fix" event. Remember that the diff is using the "fixed revision" in TestTrack. If the files do not have a "fixed revision" then you will not get any diff information.

[edit] How to use it

The application is a GUI app and the debug build executable is included. You may be able to simply run that executable if no changes are needed. Otherwise you will have to rebuild the executable after you make your changes.

The application will need the following information:

• TestTrack Connection Parameters
  • Username: The username to log into TestTrack and retrieve the list of defects and SCC files. This user must have a valid license assigned and have permission to log in via SOAP.
  • Password: The password for the user above.
  • SOAP Server Address: The address of the ttsoapcgi.exe. This needs to be in http:// format.
  • TestTrack Project: The project to connect to for defect retrieval. The application needs the username, password and SOAP server address to populate this list.
• TestTrack Filter: The filter to use to only report on the desired defects. Create the filter in TestTrack that will give you the defects you are after.
• Surround SCM Connection Paramenters:
  • Username: The Surround SCM username to pass the command line interface to run the diff command. The username must have a valid license assigned and have permissions to log in via the command line interface.
  • Password: The password for the username above.
  • Server Address: The address of the Surround SCM server.
  • Server Port Number: The port number that the Surround SCM server is running on. The default is 4900.

Once all the relevant information has been entered, click on the "Run Report" button to generate the HTML report.

Figure 2 below shows the application interface with data entered in each text box and items selected in each combo box:

[edit] Known issues

The application has not been tested so there aren't many known issues to report on. Here are some possible issues:

• Performance: SOAP is not the most efficient way to retrieve data for reporting purposes. SOAP is provided more as a way to update defects from outside of TestTrack.

If you experience performance degradation with the use of this application, you may want to consider querying the actual database instead of using SOAP.

TestTrack supports RDMBS databases and also provides a read-only ODBC driver to query the native database. If you would like to go this route I stronly suggest that you convert the database to an RDBMS format since that will allow you for more powerful querying ability.

• Unexpected data: As mentioned in the enhancements section below, more error checking could help prevent any exceptions or unexpected results. If the SCC files are in a format that the parsing logic is not expecting, the application may crash or output incorrect results. One known issue that will cause an exception is if you have SCC files attached from another SCC tool other than Surround SCM.

[edit] Improvements/enhancements

• HTML report: The format of the html report is admittedly very raw. The focus of this example is on how to get the data and not on how to create fancy HTML reports. I encourage anyone with HTML knowledge to add more lines to include in the HTML report. Some ideas could be:
  • Link to a css stylesheet that is used in your company already for company literature on your intranet.
  • Add inline stylesheet for same purpose as above.
  • Add an image link to have your company logo.
  • Change the table tag to have a consistent table width.

• Error Checking: While I did include a fair amount of error checking, it does not check for every single piece of data that the application needs to run. It may also not account for some possible exceptions.

• Options: You may want to include other options with this application. Some examples could be:
  • Output path of report.
  • Option to get files - Just like we pass the "diff" command to get the difference information, you could also pass a "get" command to retrieve the files.

[edit] Comments/Suggestions

Feel free to drop me an e-mail if you have any comments or suggestions. Just keep in mind the disclaimer. If you have any issues I may be able to help you, but only if it is something minor.

If you would like to implement a similar application but require it to be customized or rewritten for your environment (maybe your are in Linux, or use a differnt SCC tool), feel free to contact our services department, which I am a member of. We have the knowledge and skills to deliver a solution that will meet your needs.