Skip to content

GenerateReleaseNotes Tasks

Jump to bottom Edit New page
Richard Fennell edited this page Mar 29, 2016 · 28 revisions

See this blog post of more details on this task and its associated PowerShell script

This task is available as an extension in the VSTS marketplace

This task generates 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 <TYPHOONTFS\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. ###Basic Template A sample template file is shown below. It lists the build summary details and core details of each associated changeset/commit and work item.

#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.

This give an output as follows

#Release notes for build Validate-ReleaseNotesTask.Master
Build Number : 20160325.12
Build started : 25/03/16 09:07:47
Source Branch : refs/heads/master
###Associated work items
None ###Associated change sets/commits

  • ID 4e9b75b4a9d3b64a5e6abf9975b9ed1a1c29682f Added a more dump based
  • ID 3205f570a9866be5b837f88660866741cc404716 Corrected content

Template that 'dumps' out available values

This version of the template file that just dumps out all the available fields to help you find all the options open to you.

#Release notes for build $defname  
$($build)    
###Associated work items  
@@WILOOP@@  
* $($widetail) 
@@WILOOP@@  
###Associated change sets/commits  
@@CSLOOP@@  
* $($csdetail)    
@@CSLOOP@@

This give an output as follows

#Release notes for build Validate-ReleaseNotesTask.Master
@{_links=; plans=System.Object[]; id=330; buildNumber=20160325.12; status=inProgress; queueTime=2016-03-25T09:07:44.7394253Z; startTime=2016-03-25T09:07:47.6398974Z; url=https://xxx.visualstudio.com/DefaultCollection/670b3a60-2021-47ab-a88b-d76ebd888a2f/_apis/build/Builds/330; definition=; buildNumberRevision=12; project=; uri=vstfs:///Build/Build/330; sourceBranch=refs/heads/master; sourceVersion=4e9b75b4a9d3b64a5e6abf9975b9ed1a1c29682f; queue=; priority=normal; reason=manual; requestedFor=; requestedBy=; lastChangedDate=2016-03-25T09:07:47.317Z; lastChangedBy=; parameters={"system.debug":"false","BuildConfiguration":"release","BuildPlatform":"any cpu"}; orchestrationPlan=; logs=; repository=; keepForever=False}
###Associated work items
None ###Associated change sets/commits

###How the Template Works 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

  • Note 3: Take care when using the $workItems and $changesets objects. These can be empty/null, single instances or arrays depending upon the returned values from the VSTS REST API; hence their behaviour (due to the way PowerShell works) changes. If you always want to enforce they are treated as arrays, even if only a single item, use the for @($workItems).

Usage on a VSTS build workflow

The build task needs to be built and uploaded as per the standard process detailed in the Building the tasks in this repo

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.

Extension 1 vss-extension.json (Edited for new paths) readme.md license.md images (for extension) logo.png screenshot1.png Task 1 (PowerShell based new layout) src icon.png task.json mytask.ps1 tasklibrary.psm1 (optional as needed) test mytask.tests.ps1

Add a custom sidebar
Clone this wiki locally