IMPORTANT - There have been a number of major versions of this extension each with breaking changes, this is because

• V1 which used the preview APIs and is required if using TFS 2018 as this only has older APIs. This version is not longer shipped in the extension, but can be download from GitHub
• V2 was a complete rewrite by @gregpakes using the Node Azure DevOps SDK, with minor but breaking changes in the template format and that oAuth needed to be enabled on the agent running the tasks. At 2.27.x KennethScott added support for Handlbars templates.
• V3 removed support for the legacy template model, only handlebars templates supported as this is a far more flexible solution and allow much easier enhancement of this task.
• V4 swapped to support the Node 16 task runner, but no functional or templating changes from V3

Overview of the Cross Platform Release Notes Generator (Version 3 and later)

This task generates a release notes file based on a user defined Handlbars template. It can be using inside any Azure DevOps Classic Build, Classic Release or Multistage YAML Pipeline.

The data source for the generated Release Notes is the Azure DevOps REST API's comparison calls that are also used by the Azure DevOps UI to show the associated Work items and commit/changesets between two builds/releases. Hence this task should generate the same list of work items and commits/changesets as the Azure DevOps UI, though it attempts to enrich this core data with extra information where possible.

Detailed Documentation - The WIKI

Full documentation can be found in the project WIKI

• The page containing the same overview of the task as in the Azure DevOps Marketplace
• The page containing the automatically generated full YAML usage

Local Testing (outside Azure Pipelines) of the Task & Templates

To speed the development of this tool and it's templates a tool is provided in this repo to allow local testing. This allows the task to be run against a build/release in a repeatable controllable manner. This makes for much easier debugging of the task code and Handlebar based templates. The usage is

1. Create a settings files, this includes all the parameter your would set for the task and one injected by the Azure Pipeline Agent
2. Run the command (as a minimum) to run the task is node GenerateReleaseNotesConsoleTester.js --filename build-settings.json --pat <Azure-DevOps-PAT>

Usage Patterns

Use Cases

The a video on usage of this task is discussed in this DDD Community Conference Session

There are various ways that the task can be used. A common pattern is to use the task multiple times in a CI/CD pipeline.

1. Run once for every CI build, so you get the build notes of what is new in that build
2. Run as part of a CD release stage, checking against the last successful deployment to that stage, to generate the release notes specific to that release to a given environment.

Possible sets of parameters depending on your usage are summarized below

Where do WI and Changesets come from?

At it's core this task uses the Azure DevOps REST API to get the list of work items and commits/changesets either directly associated with a build, or between two builds/releases (see above).

However, there are also other means to supplement these lists by setting the following parameters

• To get parent and child work items of those directly associated with the build/release set getAllParents and getParentsAndChildren parameters
• To get manually linked work items set the checkForManuallyLinkedWI parameter
• To match commits to Azure DevOps PR cross project within the organisation set the searchCrossProjectForPRs parameter
• To use a WIQL query to get additional work items set the wiqlWhereClause and wiqlFromTarget parameters or the wiqlSharedQueryName parameter

The Template

There are sample Handlebar templates in the project code repo that just produce basic releases notes for both Git and TFVC based releases. Most samples are for Markdown file generation, but it is possible to generate any other format such as HTML by altering the static entries in the templates.

Note With V3.68.x it is possible to pass more than one template into the task. Thus allowing multiple documents to be generated from a single copy of the task. To do this provide a comma separated list of files in both the templatefile and outputfile parameters.

Handlebar Templates

A basic Handlebars template is as follows. What is done behind the scenes is that each {{properties}} block in the template is expanded by Handlebars. The {{properties}} can be placed inside {{#foreach}} loops to process array based properties e.g list of Work Items.

## Build {{buildDetails.buildNumber}}
* **Branch**: {{buildDetails.sourceBranch}}
* **Tags**: {{buildDetails.tags}}
* **Completed**: {{buildDetails.finishTime}}
* **Previous Build**: {{compareBuildDetails.buildNumber}}

## Associated Pull Requests ({{pullRequests.length}})
{{#forEach pullRequests}}
* **[{{this.pullRequestId}}]({{replace (replace this.url "_apis/git/repositories" "_git") "pullRequests" "pullRequest"}})** {{this.title}}
* Associated Work Items
{{#forEach this.associatedWorkitems}}
   {{#with (lookup_a_work_item ../../relatedWorkItems this.url)}}
    - [{{this.id}}]({{replace this.url "_apis/wit/workItems" "_workitems/edit"}}) - {{lookup this.fields 'System.Title'}}
   {{/with}}
{{/forEach}}
* Associated Commits (this includes commits on the PR source branch not associated directly with the build)
{{#forEach this.associatedCommits}}
    - [{{this.commitId}}]({{this.remoteUrl}}) -  {{this.comment}}
{{/forEach}}
{{/forEach}}

# Global list of WI with PRs, parents and children
{{#forEach this.workItems}}
{{#if isFirst}}### WorkItems {{/if}}
*  **{{this.id}}**  {{lookup this.fields 'System.Title'}}
   - **WIT** {{lookup this.fields 'System.WorkItemType'}}
   - **Tags** {{lookup this.fields 'System.Tags'}}
   - **Assigned** {{#with (lookup this.fields 'System.AssignedTo')}} {{displayName}} {{/with}}
   - **Description** {{{lookup this.fields 'System.Description'}}}
   - **PRs**
{{#forEach this.relations}}
{{#if (contains this.attributes.name 'Pull Request')}}
{{#with (lookup_a_pullrequest ../../pullRequests  this.url)}}
      - {{this.pullRequestId}} - {{this.title}}
{{/with}}
{{/if}}
{{/forEach}}
   - **Parents**
{{#forEach this.relations}}
{{#if (contains this.attributes.name 'Parent')}}
{{#with (lookup_a_work_item ../../relatedWorkItems  this.url)}}
      - {{this.id}} - {{lookup this.fields 'System.Title'}}
      {{#forEach this.relations}}
      {{#if (contains this.attributes.name 'Parent')}}
      {{#with (lookup_a_work_item ../../../../relatedWorkItems  this.url)}}
         - {{this.id}} - {{lookup this.fields 'System.Title'}}
      {{/with}}
      {{/if}}
      {{/forEach}}
{{/with}}
{{/if}}
{{/forEach}}
   - **Children**
{{#forEach this.relations}}
{{#if (contains this.attributes.name 'Child')}}
{{#with (lookup_a_work_item ../../relatedWorkItems  this.url)}}
      - {{this.id}} - {{lookup this.fields 'System.Title'}}
{{/with}}
{{/if}}
{{/forEach}}
   - **Tested By**
{{#forEach this.relations}}
{{#if (contains this.attributes.name 'Tested By')}}
{{#with (lookup_a_work_item ../../testedByWorkItems  this.url)}}
      - {{this.id}} - {{lookup this.fields 'System.Title'}}
{{/with}}
{{/if}}
{{/forEach}}
{{/forEach}}

# Global list of CS ({{commits.length}})
{{#forEach commits}}
{{#if isFirst}}### Associated commits{{/if}}
* ** ID{{this.id}}**
   -  **Message:** {{this.message}}
   -  **Commited by:** {{this.author.displayName}}
   -  **FileCount:** {{this.changes.length}}
{{#forEach this.changes}}
      -  **File path (TFVC or TfsGit):** {{this.item.path}}
      -  **File filename (GitHub):** {{this.filename}}
{{/forEach}}
{{/forEach}}

## List of WI returned by WIQL ({{queryWorkItems.length}})
{{#forEach queryWorkItems}}
*  **{{this.id}}** {{lookup this.fields 'System.Title'}}
{{/forEach}}

## Manual Test Plans
| Run ID | Name | State | Total Tests | Passed Tests |
| --- | --- | --- | --- | --- |
{{#forEach manualTests}}
| [{{this.id}}]({{this.webAccessUrl}}) | {{this.name}} | {{this.state}} | {{this.totalTests}} | {{this.passedTests}} |
{{/forEach}}

## Global list of ConsumedArtifacts ({{consumedArtifacts.length}})
| Category | Type | Version Name | Version Id | Commits | Workitems |
|-|-|-|-|-|-|
{{#forEach consumedArtifacts}}
 |{{this.artifactCategory}} | {{this.artifactType}} | {{#if versionName}}{{versionName}}{{/if}} | {{truncate versionId 7}} | {{#if this.commits}} {{this.commits.length}} {{/if}} | {{#if this.workitems}} {{this.workitems.length}} {{/if}} |
{{/forEach}}

## Artifacts published by build ({{publishedArtifacts.length}})
| Name| Type |
|-|-|-|
{{#forEach publishedArtifacts}}
 |{{this.name}} | {{this.resource.type}} | 
{{/forEach}}

IMPORTANT Handlebars based templates have different objects available to the legacy template used in V2 of this extension. This is a breaking change, so watch out if migrating.

IMPORTANT You can find more sample templates and extensions here

Objects Available in Templates

The are a wide range of objects available to get data from within templates. Some are always available, some only available in specific usage scenarios e.g only inside Multi-STage YAML

Common objects (Always Available)

Release objects (only available in a Classic UI based Releases)

Build objects (available for Classic UI based builds and any YAML based pipelines)

Note: To dump all possible values via the template using the custom Handlebars extension {{json propertyToDump}} this runs a custom Handlebars extension to do the expansion. There are also options to dump these raw values to the build console log or to a file. (See below)

Note: if a field contains escaped HTML encode data this can be returned its original format with triple brackets format {{{lookup this.fields 'System.Description'}}}

Handlebar Extensions

With 2.28.x support was added for Handlebars extensions in a number of ways:

The Handlebars Helpers extension library is pre-load, this provides over 120 useful extensions to aid in data manipulation when templating. They are used the form

## To confirm the Handlebars-helpers is work
The year is {{year}}
We can capitalize "foo bar baz" {{capitalizeAll "foo bar baz"}}

In addition to the Handlebars Helpers extension library, there are also some custom Helpers pre-loaded specific to the needs of this Azure DevOps task

• json that will dump the contents of any object. This is useful when working out what can be displayed in a template, though there are other ways to dump objects to files (see below)

## The contents of the build object
{{json buildDetails}}

• lookup_a_work_item this looks up a work item in the global array of work items based on a work item relations URL. Can be used for parent, child or testd by relations

Watch out for the number ../ required, it depends on how deep you foreach nesting is.

{{#forEach this.relations}}
{{#if (contains this.attributes.name 'Parent')}}
{{#with (lookup_a_work_item ../../relatedWorkItems  this.url)}}
      - {{this.id}} - {{lookup this.fields 'System.Title'}}
      {{#forEach this.relations}}
      {{#if (contains this.attributes.name 'Parent')}}
      {{#with (lookup_a_work_item ../../../../relatedWorkItems  this.url)}}
         - {{this.id}} - {{lookup this.fields 'System.Title'}}
      {{/with}}
      {{/if}}
      {{/forEach}}
{{/with}}
{{/if}}
{{/forEach}}

## Associated Pull Requests ({{pullRequests.length}})
{{#forEach pullRequests}}
* **[{{this.pullRequestId}}]({{replace (replace this.url "_apis/git/repositories" "_git") "pullRequests" "pullRequest"}})** {{this.title}}
* Associated Work Items
{{#forEach this.associatedWorkitems}}
   {{#with (lookup_a_work_item ../../relatedWorkItems this.url)}}
    - [{{this.id}}]({{replace this.url "_apis/wit/workItems" "_workitems/edit"}}) - {{lookup this.fields 'System.Title'}}
   {{/with}}
{{/forEach}}
* Associated Commits (this s commits on the PR source branch not associated directly with the build)
{{#forEach this.associatedCommits}}
    - [{{this.commitId}}]({{this.remoteUrl}}) -  {{this.comment}}
{{/forEach}}
{{/forEach}}

• lookup_a_pullrequest this looks up a pull request item in the global array of pull requests based on a work item relations URL

{{#forEach this.relations}}
{{#if (contains this.attributes.name 'Pull Request')}}
{{#with (lookup_a_pullrequest ../../pullRequests  this.url)}}
      - {{this.pullRequestId}} - {{this.title}}
{{/with}}
{{/if}}
{{/forEach}}

• get_only_message_firstline this gets just the first line of a multi-line commit message
• lookup_a_pullrequest_by_merge_commit this looks up a pull request item in an array of pull requests based on a last merge commit ID

## Associated Pull Requests ({{pullRequests.length}})
{{#forEach pullRequests}}
* **[{{this.pullRequestId}}]({{replace (replace this.url "_apis/git/repositories" "_git") "pullRequests" "pullRequest"}})** {{this.title}}
* Associated Work Items
{{#forEach this.associatedWorkitems}}
   {{#with (lookup_a_work_item ../../relatedWorkItems this.url)}}
    - [{{this.id}}]({{replace this.url "_apis/wit/workItems" "_workitems/edit"}}) - {{lookup this.fields 'System.Title'}}
   {{/with}}
{{/forEach}}
* Associated Commits (this includes commits on the PR source branch not associated directly with the build)
{{#forEach this.associatedCommits}}
    - [{{truncate this.commitId 7}}]({{this.remoteUrl}}) - {{get_only_message_firstline this.comment}}
    {{#with (lookup_a_pullrequest_by_merge_commit ../../inDirectlyAssociatedPullRequests  this.commitId)}}
      - Associated PR {{this.pullRequestId}} - {{this.title}}
    {{/with}}
{{/forEach}}
{{/forEach}}

• lookup_a_test_configuration this gets the test configuration related to a manual test

## Manual Test Plans with test details
{{#forEach manualTests}}
### [{{this.id}}]({{this.webAccessUrl}}) {{this.name}} - {{this.state}}

| Test | Outcome | Configuration |
| - | - | - |
{{#forEach this.TestResults}}
| {{this.testCaseTitle}} | {{this.outcome}} | {{#with (lookup_a_test_configuration ../../manualTestConfigurations this.configuration.id)}} {{this.name}} {{/with}} |
{{/forEach}}
{{/forEach}}

Finally there is also support for your own custom extension libraries. These are provided via an Azure DevOps task parameters holding either a block of JavaScript or the path to filename containing the JavaScript which is loaded into the Handlebars templating engine.

Either as inline javaScript

Note: Inline JavaScript can be entered in the YAML as a single line or a multi-line parameter as follows using the | operator

- task: XplatGenerateReleaseNotes@4
   inputs:
      outputfile: '$(Build.ArtifactStagingDirectory)\releasenotes.md'
      # all the other parameters required
      customHandlebarsExtensionCode: |
         module.exports = {foo() {
            return 'Returns foo';
         }};

Or the custom extension can be passed as file

- task: XplatGenerateReleaseNotes@4
   inputs:
      outputfile: '$(Build.ArtifactStagingDirectory)\releasenotes.md'
      # all the other parameters required
      customHandlebarsExtensionFile: $(System.SourceDirectory)\customcode.js

Either way it can be consumed in a template as shown below

## To confirm our custom extension works
We can call our custom extension {{foo}}

As custom modules allows any JavaScript logic to be injected for bespoke needs they can be the solution to your own bespoke filtering and sorting needs. You can find sample of custom modules and how to sructure your custom modules in the Handlebars section of the sample templates section of this repo

Task Parameters

Important: The most up to date, automatically created, parameter documention can be found on the YAML Page usage page in the project WIKI

Once the extension is added to your Azure DevOps Server (TFS) or Azure DevOps Services, the task should be available in the utilities section of 'add tasks'

The task takes the following parameters

Output location

When using this task within a build then it is sensible to publish the release notes files as a build artifacts.

However, within a release there are no such artifacts location. Hence, it is recommended that a task such as the WIKI Updater is used to upload the resultant file to a WIKI. Though there are other options such as store the file on a UNC share, in an Azure DevOps Artifact or sent as an email.

Troubleshooting

Local Debugging and Template Generation

Look at using the local console testing tool to repeatedly test your templates against a specific pipeline.

This is useful when developing your own templates, or if you have an issue you can added extra logging or potential fixes and test them prior to deploying the task.

Dumping the JSON payload

You can dump the JSON payload passed into the Handlebars template using the dumpPayloadToConsole and dumpPayloadToFile|dumpPayloadFileName parameters, the latter is the recommended approach due to the volume of content.

This file can be very useful when working out what can be exposed via a Handlebars template.

Timeouts

This task makes many calls to the Azure DevOps REST API, the volume depends on the number of associated items with a build. This volume of calls can result in timeouts, it is assumed this is due to throttling by the API. If a timeout occurs the task fails with an error in the form

Error: connect ETIMEDOUT 13.107.42.18:443

This is an issue with the underlying Azure DevOps Node SDK or REST API endpoints, not this task. Hence, an issue has been raised in the the appropriate Repo #425

Historically the only workaround has been to always place this task, and any associated tasks e.g. one that upload the generated release notes to a WIKI, in a dedicated YML pipeline job. This allows the task to be easily retried without rerunning the whole pipeline. However, with 3.37.x the error traps have been changed in the task to treat any error that occurs whilst accessing the API as a warning, but allow the task to run on to try to generate any release notes it can with the data it has managed to get. This is far from perfect but a bit more robust.

OAUTH Scope limiting what Associated Items can be seen

This task uses the build agent's access OAUTH token to access the Azure DevOps API. The permissions this identity has is dependant upon the the Job authorization scope.

Cross project permissions are made more complex by the new default settings for recently created Team Projects (created since late 2020). These can effect this task's operation why trying to find associated items from other Team Projects.

Note This setting is not a problem in older Team Projects, where the default setting to off

So, if you find that the workItems and relatedWorkItems objects are unexpectedly empty arrays when you expect values from other Team Projects check that the project settings:

Project Settings > Pipelines > Limit job authorization scope to current project for release pipelines

and

Project Settings > Pipelines > Limit job authorization scope to current project for non-release pipelines

they should both be set to disabled

Note If you wish to confirm this is an issue you can inject a different PAT using the overridePat parameter. This PAT will be used in place of the OAUTH Token