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!
Leave a Comment
However, when digging into the documentation, a different picture immerges.