Hands-on Demo – Automating release notes with GitHub

Hands-on Demo – Automating release notes with GitHub

Automating release notes generation helps streamline the process of documenting changes for each release. GitHub provides features to automatically generate release notes, which can be customized using templates.

1. Creating Automatically Generated Release Notes

GitHub allows you to automatically generate release notes based on commit messages, pull requests, and issues. Here’s how you can set it up:

Steps to Automatically Generate Release Notes:

1. Navigate to your repository on GitHub.

2. Click the Releases tab.

3. Click Draft a new release.

4. Under the Release notes section, you will see options for automatically generating release notes based on:

   • Commit messages

   • Pull requests

   • Issues

5. GitHub will generate a summary of changes based on the selected option.

2. Configuring Automatically Generated Release Notes Template

You can customize how the release notes are generated by configuring a template for release notes.

Steps to Configure Release Notes Template:

1. Navigate to Settings in your repository.

2. Click on Actions > Workflow Templates.

3. Create a new workflow or edit an existing one that includes steps for generating release notes.

4. Example workflow using a template:

   xxxxxxxxxx
   21
   1
   name: Create Release Notes
   2
   on:
   3
   push:
   4
      branches:
   5
         - main
   6
   jobs:
   7
   generate-release-notes:
   8
      runs-on: ubuntu-latest
   9
      steps:
   10
         - name: Checkout Repository
   11
         uses: actions/checkout@v3
   12
         - name: Generate Release Notes
   13
         uses: actions/github-script@v3
   14
         with:
   15
            script: |
   16
               const { context } = require('@actions/github');
   17
               const { context: { payload } } = context;
   18
               const changelog = context.payload.commits.map(commit => commit.message).join('\\n');
   19
               console.log(changelog);
   20
            outputs:
   21
               release-notes: ${{ steps.changelog.outputs.release-notes }}
   

5. Customize the release notes format by editing the GitHub Actions workflow to include specific sections, like features, bug fixes, or breaking changes.

3. Adding Custom Templates for Release Notes

You can further enhance the release notes by defining a custom template.

For example, including sections like:

• Features

• Fixes

• Enhancements

• Known Issues

Example Custom Template:

xxxxxxxxxx
9
1
# Release Notes for v{{ github.ref_name }}
2
## Features
3
{{#features}}
4
- {{title}}: {{description}}
5
{{/features}}
6
## Bug Fixes
7
{{#bugs}}
8
- {{title}}: {{description}}
9
{{/bugs}}

Customize and map the JSON output to desired sections using actions/github-script or similar workflows.

4. Benefits of Automating Release Notes

1. Consistency: Automatically generated notes ensure a consistent format across releases.

2. Efficiency: Saves time by eliminating manual creation of release notes.

3. Customization: Provides flexibility to customize release notes templates according to your project needs.

Summary

By automating release notes, teams can ensure that updates are documented accurately and efficiently, reducing manual effort and improving collaboration.