Skip to main content

How-to Generate Release Change List Automatically

Introduction​

This guide describes an automatic process for extracting and displaying the list of changes between two baselines. The process produces markdown content that can be included in release notes for intermediate internal builds or official releases delivered to customers.

The change list is a fundamental ingredient of the release notes document, which typically contains more information and can be styled, approved, and stored in different ways.

Intended for​

Configuration managers, release owners, product owners, quality control managers, and test engineers.

Activities​

RC-1

Install extension​

If not already available, install Generate Release Notes (Cross-platform) in the Azure DevOps (ADO) collection/organization.

Define Handlebars template​

Create a Handlebars template following the available examples in the documentation or reuse a template from another project. One example is in the Templates section. Save the template as a markdown file.

If needed, see Content of the automatic release change list for further information regarding the content and layout of the generated list.

Add a task to the pipeline​

Add the "XplatGenerateReleaseNotes" task to the pipeline to generate release notes. Parameters may vary according to the type of pipeline or the stages.

How to identify the previous baseline to compare with?

  • By previous execution: the last successful or partially successful pipeline.
  • By stage: the last successful or partially successful pipeline that reached a particular stage.
  • By ID: a specific pipeline ID.
  • By tag: the last or partially successful pipeline with a given tag.
            - task: XplatGenerateReleaseNotes@3
              inputs:
                outputfile: '$(Agent.TempDirectory)/ReleaseNotes/ReleaseNotes.md'
                templatefile: '$(Build.SourcesDirectory)/releasenotestemplate.md'
                templateLocation: 'File'
                dumpPayloadToFile: true
                dumpPayloadFileName: $(Agent.TempDirectory)/ReleaseNotes/dump.json
                replaceFile: true
                getParentsAndChildren: true
                getAllParents: true
                getIndirectPullRequests: false
                stopOnError: true
                considerPartiallySuccessfulReleases: true
                checkForManuallyLinkedWI: false
                wiqlFromTarget: 'WorkItems'
                checkStage: true
                showOnlyPrimary: false
                searchCrossProjectForPRs: false
                overrideStageName: 'SIT'

Publish the release change list​

According to the needs of the project, make the output available.

Some options are:

  • Publish pipeline artifact.
  • Publish to a wiki (in a new branch to be reviewed).
  • Copy to DMS, where a workflow will be initiated.
  • Further, process the output to export as a pdf or other format or add additional content.

Execute the pipeline​

Done!

Details​

Why identify changes between baselines?​

Knowing the list of changes from a previous baseline is helpful, primarily when a new baseline is delivered to a receiver, for example:

  • When delivering a baseline to the system integration test (SIT) / system type test (STT) team:
    • What has changed from the previously tested baseline?
    • What completed features or bug fixes can be tested?
  • When releasing a baseline to customers:
    • What new features are available?
    • What customer-known issues have been fixed?
  • When required to provide evidence of correct traceability or release completion:
    • What are the parents/children of changed work items?
    • Are parents/children complete, or are there any misaligned items?
    • What tests are linked to the changes?

Tools​

ADO stores traceability data such as links between code changes and work items, work items and their linked parents/children, pipeline execution details, and more. Traceability data can automatically generate a list of changes between two baselines.

RC-2

Multiple tools are currently used in PCP for this purpose. One of these tools lists changes made to the PCP R&D process website.

In this guide, Generate Release Notes (Cross-platform) is recommended because it can manage complex pipelines with multiple artifacts, and it supports many types of pipelines:

  • Classic build pipelines.
  • Classic release pipelines.
  • yaml pipelines.
  • "Simple" pipelines that do not consume artifacts from other pipelines.
  • "Integration" pipelines that consume artifacts from other pipelines.
  • Pipelines with only one stage.
  • Pipelines with multiple stages.

The following diagram shows how the list of changed work items for build and release notes is generated automatically by a yaml release pipeline that consumes multiple artifacts. The output is a markdown file published as a pipeline artifact.

RC-3

Content of the automatic release change list​

The content and layout of the output file can be completely customized. They are defined by a Handlebars template and well described in the Generate Release Notes (Cross-platform) documentation, which includes many examples.

A change list could contain:

  • Details of the current and previous releases that reached the SIT/STT stage
  • For each component:
    • Link to wiql query that shows the tree of changed work items and their parents
    • List of completed features since the previous release (only completed business features are included, while enablers, architecture features, and incomplete features are not listed).
    • List of fixed bugs since the previous release (only completed bugs).
  • Query to display the list of known bugs in the wiki.
Owner: Configuration Management Team