June 4, 2009

Distributing Change Information

Surround SCM
Sometimes there is a need to compile and share a information about changes in software. The most common example of this is release notes. I remember a customer once asking me for something similar only their scenario was very unique. The customer developed custom third party components, and when they shipped a new version to a customer, they wanted to include a list of all changes of the software. So in this article I address different ways to accomplish this. I will address the Release Notes in TestTrack, using Surround SCM triggers to capture change information, and using reports. [toc]

Building Release Notes

TestTrack Release Notes

Step by step

I assume that you are already familiar with the manual way to create release notes in TestTrack Pro. To do this, right click on a defect and select "Realease Note" from the context menu (also available from the Activities menu and workflow toolbars).

Figure 1 - Release Notes

Note: This may not be available if the Release Notes event is disabled in your workflow. Type in the release note specific to that defect and then select the version that you would like to include this change.

Figure 2 - Sample releate note

To compile the release notes, simple select File > Build Release Notes... In this example we only want to compile release notes for the version we indicated in the note we entered in figure 2 above.

Figure 3 - Building release notes

You can optionally use a filter to only query a specific subset of defects. The sample output is shown below.

Figure 4 - Sample releate notes

Pros & cons

This has some pros and cons: Pros - The compiled list is pretty much ready to be released with a build. Cons - Manually enter everything, each release note starts from scratch.

Including Comments of the Fix Event in the Release Notes

In TestTrack Pro, you can configure an event so the comments entered in the event dialog window are included in the release notes for that version. The benefit of this approach is that it may avoid double work. A lot of times what is included in the release notes is the similar to the comments made when a fix event is performed in TestTrack or when a file is checked in. These comments can also be entered in the fix dialog window from Surround SCM. If you have both TestTrack Pro and Surround SCM, the process could be as follows:
  • Developer checks in a file.
  • Attaches it to a defect in TestTrack Pro.
  • Performs a fix event. In the fix dialog box, the developer enters in the comments whatever should show in the release notes or something similar.

Step by step

First, the workflow in TestTrack needs to be configured so the comments are included in the release notes. To do this, select Tools>Administration>WorkflowNOTE: You can not edit the workflow while users are logged in, so you will have to either get everyone to log out, or do this during off hours. The Configure Workflow window appears.

Figure 5 - Configure Workflow

Select the events tab and select the fix event and click on Edit. The “Edit Event” window appears. Check the box next to Include event notes with the release notes.

Figure 6 - Edit fix event dialog

Click OK, you do not have to restart the server or log out and back in for this to take effect. The change should take place right away.
Use Case
The user works on a source code file and it is time to check it in. In the check in dialog, the user clicks on the Attach to Defects button. In most IDEs you should be able to access an advanced option for check ins. There you should see a check box Prompt for Seapine Suite integration. Checking this box will display the defect list in the IDE.

Figure 7 - Check in dialog

The Attach to Defect window comes up. The user selects the appropriate defect (must be on a fixable state –i.e. the fix event can be performed from the current state) and attaches it to the file.

Figure 8- Attach to defect dialog

The user clicks on the Fix event enters a version of release, comments and other information.

Figure 9- Fix event dialog accessed from Surround SCM

User clicks OK on the various windows to commit the fix event, the attach to defect event, and to actually check in the file. Note: That the fix event comments are now part of the check in comment in Surround SCM.

Figure 10- Check in dialog with fix event comments

Building the Release Notes

Not going to go into detail here, since we already covered this above. Just going to include an updated screenshot showing the comments entered for the fix event.

Figure 11 - Release notes including the fix event

Pros & Cons

Pros - Avoids some double effort since users will usually enter comments when check in code or performing the fix event. Cons - You may prefer check-in comments to be more about the actual change to the source code file, not the change in the software that is a result of the changes in the source code file. But even in this scenario, the person in charge of compiling the release notes will not be starting from scratch. While the check-in comments may not be exactly what should be released to customers, it may give this person a good starting point.

What did we learn, if anything?

Even if you do not think that the check in comments should be used for release notes, entering the fix event notes from Surround SCM ensures that the same comments are used for the check in event. This gives you uniformity. Also if you don't care about the check in or fix events being included in the release notes, there may be other event in your workflow that may include comments that could be included in the release notes. Maybe you want to replace the Release Note event in TestTrack with your own. One that would move the defect to a state that indicates that the release notes have been entered.

Using the Comments from Check Ins

The following does require some customization on your side, or you could hire Seapine services to write something to exactly meet your needs. Surround SCM has a feature called Triggers. These triggers are fired off when a change event on a file takes place, like a check in, and when a trigger is fired, it can do a series of actions. One of these actions is to run a script or batch file. These scripts can run commands from the Surround SCM Command Line Interface, can grab information about the event that fired off the trigger, send an e-mail, etc… So my idea is that you create a batch file that writes information about the check-in to some text file on the Surround SCM server machine. When you need to distribute files or build release notes, you would go to this text file. You could base release notes on this file, or include this file when you FTP files over to a client. Here is how I would set up such trigger:

Create a batch file

First, I am going to create a batch file that will log information about the check in event to some text file. I am using the Surround SCM environment variables listed in the Surround SCM user guide, I have also posted them as part of an article in the Seapine Software Surround SCM wiki. I create a simple batch file to write out the date of the check in and the comments. You could use more variables and also include the user, the repository, the branch, etc… My batch file only contains this:
echo %SSCM_DATE%>>D:batchrelnotes.txt

echo - %SSCM_COMMENTS%>>D:batchrelnotes.txt
I save it as “relnotescreato.bat” under “D:batch” on the server where the Surround SCM server is running. Keep in mind that the Surround SCM server is what runs the batch file, so the file must be accessible to the server.

Create the trigger

In the Surround SCM client, select Tools > Administration > Triggers I name the trigger and set the branch and repository where I want this trigger to run.

Figure 12 - Add triger dialog - Pre-Conditions tab

I then set the trigger to fire off after a check in event occurs.

Figure 13 - Add triger dialog - Trigger When tab

Lastly, I set the trigger to run the batch file created above:

Figure 14- Add triger dialog - Actions tab

Click OK to save the trigger.

Use case

Check out and edit a file located in the branch and repository indicated in the trigger. When checking in the file, enter some comments, as shown below.

Figure 15 - Check in dialog

Now, I browse to the D:batch directory on the server, locate the output file (relnotes.txt) and open it. The file is shown below.

Figure 16 -Release notes created by trigger

The way the batch file is designed, any subsequent check ins are appended to the file. For the idea of distributing code, you could include more information. For example, you could also log the file name:
echo %SSCM_FILE was changed on %SSCM_DATE%>>D:batchrelnotes.txt

echo - %SSCM_COMMENTS%>>D:batchrelnotes.txt
After I check in the same file again using the same trigger (I just added the above to the existing batch file), the output file now looks like this:

Figure 17 - Release notes created by trigger

Please refer to the Surround SCM User guide or to the article on our wiki that I mentioned above to see all of the variables available.

Using Surround SCM History Report

Lastly, information to a third party could also be given in the form of a report. The report could be configured to report on the following:
  • The branch and repository that contains the files you are going to distribute.
  • Set it to report only on those that have a “last modified date” later than the last time code was sent to this company.
You could also have the report to include differences information (include each line by line change). Under Tools > Reports, you can create a report that does this. First, select the branch and repository to report on.

Figure - 18 Edit Report dialog

Next, select filter based on the dates.

Figure - 17 Edit Report dialog

Under Output, check the box Include difference information.

Figure - 20 Edit Report dialog

This creates a history report on the WysiCM 1.0.x branch. The report only contains actions that occurred in the date range specified. This is illustrated below.

Figure - 21 sample history report

You can save the HTML file and could send it to a third party and now they will only see those changes made since the last time, and if you want to you can even show them what lines changed.