A vNext build task and PowerShell script to generate release notes as part of TFS vNext build.

Updated 22 Mar 2016: This task is now available as an extension in the VSTS marketplace

A common request I get from clients is how can I create a custom set of release notes for a build? The standard TFS build report often includes the information required (work items and changesets/commits associate with the build) but not in a format that is easy to redistribute. So I decided to create a set to tools to try to help.

The tools are available on my github account in two forms:

• a PowerShell script that can be run upon demand from the command line
• a vNext build task that can be added to the TFS/VSTS vNext build process.

Both generate a markdown release notes file based on a template passed into the tool. The output report being something like the following:

Release notes for build SampleSolution.Master

Build Number: 20160229.3
Build started: 29/02/16 15:47:58
Source Branch: refs/heads/master

Associated work items

• Task 60 [Assigned by: Bill ] Design WP8 client

Associated change sets/commits

• ID bf9be94e61f71f87cb068353f58e860b982a2b4b Added a template
• ID 8c3f8f9817606e48f37f8e6d25b5a212230d7a86 Start of the project

The Template

The use of a template allows the user to define the layout and fields shown in the release notes document. It is basically a markdown file with tags to denote the fields (the properties on the JSON response objects returned from the VSTS REST API) to be replaced when the tool generates the report file.

The only real change from standard markdown is the use of the @@TAG@@ blocks to denote areas that should be looped over i.e: the points where we get the details of all the work items and commits associated with the build.

#Release notes for build $defname    
\*\*Build Number\*\*  : $($build.buildnumber)      
\*\*Build started\*\* : $("{0:dd/MM/yy HH:mm:ss}" -f \[datetime\]$build.startTime)      
\*\*Source Branch\*\* : $($build.sourceBranch)    
###Associated work items    
@@WILOOP@@    
\* \*\*$($widetail.fields.'System.WorkItemType') $($widetail.id)\*\* \[Assigned by: $($widetail.fields.'System.AssignedTo')\] $($widetail.fields.'System.Title')    
@@WILOOP@@    
###Associated change sets/commits    
@@CSLOOP@@    
\* \*\*ID $($csdetail.changesetid)$($csdetail.commitid)\*\* $($csdetail.comment)      
@@CSLOOP@@   

Note 1: We can return the builds startTime and/or finishTime, remember if you are running the template within an automated build the build by definition has not finished so the finishTime property is empty to can’t be parsed. This does not stop the generation of the release notes, but an error is logged in the build logs.

Note 2: We have some special handling in the @@CSLOOP@@ section, we include both the changesetid and the commitid values, only one of there will contain a value, the other is blank. Thus allowing the template to work for both GIT and TFVC builds.

What is done behind the scenes is that each line of the template is evaluated as a line of PowerShell in turn, the in memory versions of the objects are used to provide the runtime values. The available objects to get data from at runtime are

• $build – the build details returned by the REST call Get Build Details
• $workItems – the list of work items associated with the build returned by the REST call Build Work Items
• $widetail – the details of a given work item inside the loop returned by the REST call Get Work Item
• $changesets – the list of changeset/commit associated with the build build returned by the REST call Build Changes
• $csdetail – the details of a given changeset/commit inside the loop by the REST call to Changes or Commit depending on whether it is a GIT or TFVC based build

There is a templatedump.md file that just dumps out all the available fields in the PowerShell repo to help you find all the available options

Differences between the script and the task

The main difference between the PowerShell script and the build task is the way the connection is made to the REST API. Within the build task we pickup the access token from the build agent’s context. For the PowerShell script we need to pass credentials in some form or the other, either via parameters or using the default Windows credentials.

Usage

PowerShell

The script can be used in a number of ways

To generate a report for a specific build on VSTS

 .Create-ReleaseNotes.ps1 -collectionUrl https://yoursite.visualstudio.com/defaultcollection -teamproject "Scrum Project" –defname "BuildTest" -outputfile "releasenotes.md" -templatefile "template.md" -buildnumber "yourbuildnum" -password yourpersonalaccesstoken

Or for the last successful build just leave out the buildnumber

 .Create-ReleaseNotes.ps1 -collectionUrl https://yoursite.visualstudio.com/defaultcollection -teamproject "Scrum Project" –defname "BuildTest" -outputfile "releasenotes.md" -templatefile "template.md" -password yourpersonalaccesstoken

Authentication options

1. VSTS with a personal access token – just provide the token using the password parameter
2. If you are using VSTS and want to use alternate credentials just pass a username and password
3. If your are using the script with an on-premises TFS just leave off both the username and password and the Windows default credentials will be used.

In all cases the debug output is something like the following

  
VERBOSE: Getting details of build \[BuildTest\] from server \[https://yoursite.visualstudio.com/defaultcollection/Scrum Project\]  
VERBOSE: Getting build number \[20160228.2\]  
VERBOSE:    Get details of workitem 504  
VERBOSE:    Get details of changeset/commit ba7e613388c06b8440c9e7601a8d6fa29d588051  
VERBOSE:    Get details of changeset/commit 52570b2abb80b61a4a629dfd31c0ce071c487709  
VERBOSE: Writing output file  for build \[BuildTest\] \[20160228.2\].

You should expect to get a report like the example shown at the start of this post.

Build Task

The build task needs to be built and uploaded as per the standard process detailed on my vNext Build’s Wiki (am considering creating a build extensions package to make this easier, keep an eye on this blog)

Once the tool is upload to your TFS or VSTS server it can be added to a build process

The task takes two parameters

• The output file name which defaults to $(Build.ArtifactStagingDirectory)releasenotes.md
• The template file name, which should point to a file in source control.

There is no need to pass credentials, this is done automatically

When run you should expect to see a build logs as below and a releases notes file in your drops location.

Summary

So I hope some people find these tools useful in generating release notes, let me know if they help and how they could be improved.