June 4, 2009
Distributing Change Information
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 stepI 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).
Pros & consThis 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 NotesIn 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
ConfigurationFirst, 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.
Use CaseThe 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.
Building the Release NotesNot 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.
Pros & ConsPros - 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 InsThe 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 fileFirst, 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.txtI 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 triggerIn 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.
Use caseCheck 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.
echo %SSCM_FILE was changed on %SSCM_DATE%>>D:batchrelnotes.txt echo - %SSCM_COMMENTS%>>D:batchrelnotes.txtAfter 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:
Using Surround SCM History ReportLastly, 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.