How can I automatically create Azure DevOps Release Notes and how can I publish them?

A question I am often asked when consulting on Azure DevOps is ‘how can I automatically create release notes and how can I publish them?’.

Well it is for just this requirement that I have written a set of Azure DevOps Pipeline Tasks

  • Release Note Generator – to generate release notes. I strongly recommend this Cross-platform Node-based version. I plan to deprecate my older PowerShell version in the not too distant future as it uses ‘homegrown logic’, as opposed to standard Azure DevOps API calls, to get associated items.
  • Wiki Updater – to upload a page tot a WIKI.
  • WIKI PDF Generator – to convert a generated page, or whole WIKI, to PDF format.

So lets deal with these tools in turn

Generating Release Notes

The Release Note task generates release notes by getting the items associated with a build (or release) from the Azure DevOps API and generating a document based on a Handlebars based template.

  • The artefacts that can be included in the release notes are details of the build/release and associated Work Items, Commits/Changesets, Tests and Pull Requests.
  • Most of the sample templates provided are for markdown format files. However, they could easily be converted for other text-based formats such as HTML if needed.
  • The use of Handlebars are the templating language makes for a very flexible and easily extensible means of document generation. There are sample of custom extensions provided with the templates

Sample YAML for this task is as follows, not it is using an inline template but it is possible to also load the template from a file path

        - task: richardfennellBM.BM-VSTS-XplatGenerateReleaseNotes.XplatGenerate-Release-Notes.XplatGenerateReleaseNotes@3
          displayName: 'Generate Release Notes'
          inputs:
            outputfile: '$(System.DefaultWorkingDirectory)\inline.md'
            outputVariableName: OutputText
            templateLocation: InLine
            inlinetemplate: |
              # Notes for build 
              **Build Number**: {{buildDetails.id}}
              **Build Trigger PR Number**: {{lookup buildDetails.triggerInfo 'pr.number'}} 

              # Associated Pull Requests ({{pullRequests.length}})
              {{#forEach pullRequests}}
              {{#if isFirst}}### Associated Pull Requests (only shown if  PR) {{/if}}
              *  **PR {{this.id}}**  {{this.title}}
              {{/forEach}}

              # Builds with associated WI/CS ({{builds.length}})
              {{#forEach builds}}
              {{#if isFirst}}## Builds {{/if}}
              ##  Build {{this.build.buildNumber}}
              {{#forEach this.commits}}
              {{#if isFirst}}### Commits {{/if}}
              - CS {{this.id}}
              {{/forEach}}
              {{#forEach this.workitems}}
              {{#if isFirst}}### Workitems {{/if}}
              - WI {{this.id}}
              {{/forEach}} 
              {{/forEach}}

              # Global list of WI ({{workItems.length}})
              {{#forEach workItems}}
              {{#if isFirst}}## Associated Work Items (only shown if  WI) {{/if}}
              *  **{{this.id}}**  {{lookup this.fields 'System.Title'}}
                - **WIT** {{lookup this.fields 'System.WorkItemType'}} 
                - **Tags** {{lookup this.fields 'System.Tags'}}
              {{/forEach}}

              {{#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}}

How to Publish The Notes

Once the document has been generated there is a need for a decision as to how to publish it. TThere are a few options

  • Attach the markdown file as an artefact to the Build or Pipeline. Note you can’t do this with a UI based Releases as they have no concept of artefacts, but this is becoming less of a concern as people move to multistage YAML.
  • Save in some other location e.g Azure Storage or if on-premises a UNC file share
  • Send the document as an email – I have used Rene van Osnabrugge Send Email Task for this job.
  • Upload it to a WIKI using my WIKI Updater Task
  • Convert the markdown release note document, or the whole WIKI, to a PDF and use any of the above options using first my WIKI PDF Exporter Task then another task.

I personally favour the 1st and 4th options used together. Attachment to the pipeline and then upload the document to a WIKI

A sample of suitable YAML is shown below, uploading the document to an Azure DevOps WIKI. Please note that the repo URL and authentication can trip you up here so have a good read of the provided documentation before you use this task.

  - task: richardfennellBM.BM-VSTS-WIKIUpdater-Tasks.WikiUpdaterTask.WikiUpdaterTask@1
          displayName: 'Git based WIKI Updater'
          inputs:
            repo: 'dev.azure.com/richardfennell/Git%20project/_git/Git-project.wiki'
            filename: 'xPlatReleaseNotes/build-Windows-handlebars.md'
            dataIsFile: true
            sourceFile: '$(System.DefaultWorkingDirectory)\inline.md'
            message: 'Update from Build'
            gitname: builduser
            gitemail: 'build@demo'
            useAgentToken: true

But when do I generate the release notes?

I would suggest you always generate release notes every build/pipeline i.e. a document of the changes since the last successful build/pipeline of that build definition. This should be attached as an artefact.

However, this per build document will usually too granular for use as ‘true’ release notes i.e. something to hand to a QA team, auditor or client.

To address this second use case I suggest, within a multistage YAML pipeline (or a UI based release), having a stage specifically for generating release notes.

My task has a feature that it will check for the last successful release of a pipeline/release to the stage it is defined in, so will base the release note on the last successful release to that given stage. If this ‘documentation’ stage is only run when you are doing a ‘formal’ release, the release note generated will be since the last formal release. Exactly what a QA team or auditor or client might want.

In conclusion

So I hope that this post provides some ideas as to how you can use my tasks generate some useful release notes.

Update guest post on migrating TFVC projects to Git

Microsoft asked my to revise my August 2014 article on ‘Migrating a TFS TFVC team project to a Git team project’, this revised version is now live on their web site.

The changes in the revision are updated links for tools, and information on how to use the technique with VSTS now some work item customisation is available.

Upgrading BlogEngine to 3.3

I have just completed the upgrade of our Blog Server to BlogEngine 3.3. This upgrade is a bit more complex than the usual upgrade as between 3.2 to 3.3 there is a change to Razor views for all the widgets. This means you need to remove all the old widgets you have and re-add them using the new razor equivalents.

As our blog is backed by SQL, this mean a SQL script to clear down the old widgets, then a manual add of the new versions on each blog we have on our server. One point to note, if using SQL you do need to get BlogEngine 3.3 from its GitHub repo (at the time of writing, I am sure this will change) as after the formal 3.3 release on CodePlex there is a fix for an issue that stopped the editing of widget properties.

So first experiences with 3.3?

Seems much more responsive, so all is looking good

Running a SaaS service at scale

Brian Harry has done a couple of very interesting posts (post 1 and post 2) on the recent outages of the VSTS service. Whether you use VSTS or not they make interesting reading for anyone who is involved in running SaaS based systems, or anything at scale.

From the posts the obvious reading is you cannot under estimate the importance of

  • in production montoring
  • having an response plan
  • doing a proper root cause analysis
  • and putting steps in place to stop the problem happening again

Well worth a read

Live Writer becomes Open Live Writer

My primary blog editor has been Microsoft Live Writer for years, but it has always been a pain to install via Windows Essentials (as I don’t want the rest of the product), also I was never able to find the right version when I rebuilt a PC. This was not helped by the fact there has been no development of the product for years, so I struggled to remember what year version I really needed (last one was 2012 by the way).

So it is great news that the code base has gone Open Source at  http://openlivewriter.org/, and this is my first post using the new editor. Seem to work great.

Visual Studio Dev Essentials announced at Connect() with free Azure time each month

One announcement I missed at at Connect() last week was that of Visual Studio Dev Essentials. I only heard about this one whilst listening to RadioTFS’s news from Connect() programme.

Visual Studio Dev Essentials is mostly a re-packing of all the tools that were already freely available from Microsoft e.g. Visual Studio Community Edition, Tem Foundation Server Express etc.; but there are some notable additions* (some coming soon)

  • Pluralsight  (6-month subscription)—limited time only
  • Xamarin University mobile training— coming soon
  • WintellectNOW  (3-month subscription)
  • Microsoft Virtual Academy
  • HackHands Live Programming Help  ($25 credit)
  • Priority Forum Support
  • Azure credit  ($25/month for 12 months)—coming soon
  • Visual Studio Team Services account with five users
  • App Service free tier
  • PowerBI free tier
  • HockeyApp free tier
  • Application Insights free tier

*Check the Visual Studio Dev Essentials site for the detailed T&C

So if you, or a student/hobbyist you know, need great development tools sign up at Visual Studio Dev Essentials

Patterns & Practices Architecture Track at Future Decoded

In case you had not noticed, our MD and Connected Systems MVP Robert Hogg posted about the new Patterns & Practices Architecture Track he is hosting on Day 1 of the Microsoft Future Decoded event  next month in London.

This track is an additional track to the now full Future Decoded. If you are interested in attending then get in touch with enquiries@blackmarble.com, for the attention of Linda, and she can help you out with a special code (if there are still any left). This code will not only give you access to the excellent p&p track on Day One, but also the Keynotes, so please select Day One when you register!

Projects

All my active personal projects are now stored on Github

You can find specific projects in the following locations (including legacy ones).

VSTS/TFS Extensions

The following extensions can be installed on VSTS or TFS 2015.2 (or later) via the VSTS Marketplace 

Title Description Source Package
Generate Release Notes Generates a markdown release notes file based on work items associated with a build Github Marketplace
Pester Test Runner Allows Pester based tests to be run in a build Github Marketplace
StyleCop Runner Allows a StyleCop analysis to be made of files in a build Github Marketplace
Typemock TMockRunner Allows TMockrunner to wrapper MSTest, allowing Typemock test to be run on a private build agent Github Marketplace
Manifest Versioning Allows the versioning of DLLs, DacPACs, APPX and VSIX packages Github Marketplace

Visual Studio Add-ins and templates

The following items are add-ins or templates for Visual Studio

Title Description Source Package
Parameters XML Generator A Visual Studio add-in to generate a parameters.xml from a web.config file for use with MSDeploy. Github VS Gallery
MsTest Wrapper for nUnit T4 Generator for MsTest Wrappers For nUnit Tests, it dynamically creates MsTest wrappers for nUnit tests at build time Github  

Other VSTS/TFS/Visual Studio projects

 The following projects are TFS related but not packaged as extensions (yet)

Title Description Source Package
VSTS Service Hooks DSL Python based DSL that allows the easy scripting of actions when a TFS/VSTS Service Hook Alert is received Github Marketplace
Github
TFS API Scripts A selection of Scripts using different TFS/VSTS APIs Github  

Other projects

 The following projects are other projects, not specifically related to TFS

Title Description Source Package
StyleCop Command Line A command line wrapper for StyleCop so it can be called from the command prompt for PowerShell scripts Github Github

In-active projects

 The following projects are not activally being developed

Title Description Source Package
TFS Alerts DSL

Python based DSL that allows the easy scripting of actions when a TFS Alert is received (Moved from CodePlex)

(Superceeded by VSTS Service Hook DSL)

GitHub GitHub
GUI Tester An attribute based library to aid the testing of user interfaces (Moved from CodePlex) GitHub