Automating release notes in Github

Save time writing release notes!

Why are release notes important?

Here at Talis, we use release notes to communicate changes to the rest of the business. They consist of a high-level overview of the changes made, along with links to Github issues where the reader can find more details should they require it. They also contain data that can be important operationally, such as the date we deployed the release and the build number that generated the artifact. This small piece of information is vital should a bug be discovered in production and we need to trace it back to a specific change.

For example, let’s say we refactored part of our codebase, then a month later we discovered some documents were missing attributes. When the discovery is made that we are missing attributes on documents, we can find the earliest document that is missing attributes and then immediately find releases around that time. From there we can easily debug the cause of the problem, and then work on a fix as well as fixing all documents since that release.

Save time writing release notes!

As important as release notes are, don’t waste your time writing them. The process can easily be automated! For years we have had a bash script that would generate release notes. This bash script would go through all the commits since the last release and then output some markdown for you to copy and paste into the Github release. As you can imagine, it wasn’t much fun running a bash script to then copy and paste the output into Github. But it did the job we needed it to do.

Moving to Release Drafter

One of our developers, Ben, spent his personal development time (here at Talis, developers can spend half a day a week learning new technologies or anything unrelated to their current theme of work) investigating better ways to automate the creation of our release notes and subsequently gave a talk to the rest of the development team about Release Drafter. The main idea behind Release Drafter is that it will create a draft release with all the changes in master since you last published a release, you can also categorise the contents based on the tags added to the pull request. Then when you come to releasing you just add the tag and the title, then hit the publish button.

Shortly after the talk, we began trialling Release Drafter on several repositories with a custom configuration. The standout feature for us was the ability to parse commit messages with replacers. This meant we could extract data from commit messages to provide links to issues. After a week or so of trialling Release Drafter, we made the decision to roll it out across all our repositories. To do this with a custom configuration we created a .github repo in the organisation and added our config to .github/release-drafter.yml as per the documentation. We then installed Release Drafter as an app for the organisation and enabled it for the majority of our repositories.

So with a simple configuration our release notes are now generated automatically. This does require that commits start with ISSUE-<issue_number> to correctly link back to the issue within Github.

_extends: .github
name-template: Release <TAG> on YYYY-MM-DD
replacers:
  - search: '/ISSUE-(\d+)/gi'
    replace: '[ISSUE-$1](https://github.com/talis/planning/issues/$1)'
categories:
  - title: 'Features'
    label: 'feature'
  - title: 'Bug Fixes'
    label: 'bug'
template: |
  $CHANGES

Thanks…

Now our process for creating release notes has been simplified, from manually copying the output of a bash script, to editing a precompiled release draft - not a single developer misses the trusty old bash script we used to run. Thanks to the team at Release Drafter for helping to make our workflow that little bit easier.