Semantic Release Notes with Conventional Commits

Recently I wrote about how to use Conventional Commits to calculate the next release version based on semantic versioning. Today I’m going to show how to turn conventional commit messages into release notes using a simple Github Action called Semantic Release Notes Generator that I’ve written.

release-notes-generator

The action is basically just a wrapper for semantic-release/release-notes-generator which is a plugin for semantic-release, an opinionated version management tool. When trying out semantic-release I found it to be too much functionality entangled in a way I couldn’t get to work the way I wanted it to, but I really liked the release notes generator! Being a fan of the Unix philosophy, I decided to wrap it in a neat little action that I could pipe.

Usage

The generator fetches all commit messages between two git references, and feeds them into the release-notes-generator that formats the messages into a nice looking release log.

The semantic release notes generator actually uses a Github Action workflow to test itself (more about that in another post). It uses gitversion to determine next version and pipe that to the generator to generate release notes based on the commits logged since the last release.

Here’s how that could look like:

...
- name: Determine Version
  id: gitversion
  uses: gittools/actions/gitversion/execute@v0
  with:
    useConfigFile: true
    configFilePath: .github/version_config.yml
- name: Determine Release Info
  id: release
  run: |
    from_tag=$(git tag --points-at ${{ steps.gitversion.outputs.versionSourceSha }} | grep -m 1 ^v[0-9]*\.[0-9]*\.[0-9]* | head -1)
    tag=v${{ steps.gitversion.outputs.majorMinorPatch }}

    echo "::set-output name=tag::$tag"
    echo "::set-output name=from_ref_exclusive::$from_ref_exclusive"
- name: Create Tag
  uses: actions/github-script@v3
  with:
    script: |
      github.git.createRef({
        owner: context.repo.owner,
        repo: context.repo.repo,
        ref: "refs/tags/${{ steps.release.outputs.tag }}",
        sha: "${{ steps.gitversion.outputs.sha }}"
      });
- name: Generate Release Notes
  id: release_notes
  uses: fresa/release-notes-generator@v0
  with:
    version: ${{ steps.release.outputs.tag }}
    from_ref_exclusive: ${{ steps.release.outputs.from_ref_exclusive }}
    to_ref_inclusive: ${{ steps.release.outputs.tag }}
- name: Create Release
  uses: softprops/action-gh-release@v1
  with:
    body: ${{ steps.release_notes.outputs.release_notes }}
    tag_name: ${{ steps.release.outputs.tag }}
...

It calculates the next version and finds the last release’s git reference. Then it creates a tag to mark the next release, which also will be used as to_ref_inclusive when generating the release notes. Lastly it creates the Github release using the release notes and the tag created.

If there’s a need to change the release notes, it’s always possible to edit the release in Github either after the release has been published or by releasing it as a draft and manually publishing it after a review.

Summary

release-notes-generator is a great tool for generating release notes when using conventional commits. With Semantic Release Notes Generator you can in an unopiniated way choose how to use release notes within your automated continuous delivery processes!