Arthur Garcia - Make it Easier to Release Release Notes

API The Docs Virtual 2022 Recap

This talk was presented at API The Docs Virtual 2022 event series on 12 October. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit the talk listing page for an overview of all presentations!

Arthur Garcia

Senior Program Manager, Commercial Software Engineering at Microsoft

Arthur's presentation (video recording)



Q&A

  • I have teams working across the globe, how organized do…say the JiRa tickets need to be for this to be a success? Do you have templates?
  • What can possibly go wrong?
  • If your product is more closed source, how might you exclude more internal changes from public release notes?
  • This is a great solution. We'd like to do something similar but we are using Jira. What scripts/languages should we consider using to build something like this for Jira?

Things you can do with APIs: Building release notes

A lot of Program Managers have problems with getting release notes out because:

  • multiple teams are involved in the release process,
  • they have many user stories.

Usually, composing a release note from all the necessary data requires manual work. In this demo session, Arthur will show you a better way of doing it. He’ll use an API to automate both the release notes writing and the publishing process.

First, he demonstrates how you can create a Personal Access Token (PAT) key to get full control over the necessary services and resources (like the Wiki). Then, he jumps right into his PowerShell code, and teaches you how to use the Azure DevOps API to generate release notes in two different ways.

Creating release notes from a query

Create a query for the work items (user stories, bugs, tasks) and artifacts you have, and send all of them through the API to generate release notes.

In this part of the demo, you’ll hear how you can:

  • make authorization work,
  • collect the required modules,
  • create the definitions page,
  • display current and future releases in the same wiki page,
  • set the information and sections you want to include,
  • customize the look and feel of the output,
  • create a new wiki page and populate it with the content of the release notes.

The resulting release notes appear on the wiki page right after the code has finished running.

Creating release notes from a build tag

Tag your builds, then generate release notes from the builds, build changes, and work items using the API.

Arthur’s code finds all of the things that were checked into the builds, then it rolls up to the related user stories, then displays only the user stories.

In this part of the demo, Arthur shows you how you can:

  • make authorization work,
  • collect the required build tags,
  • grab the builds, work items, and stages,
  • pull down the artifacts,
  • return the array of the of the things that you've built,
  • customize the look and feel of the output,
  • create a new wiki page and populate it with the content of the release notes.

The resulting release notes appear on the wiki page right after the code has finished running.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.