Release notes management

How do you manage your OSS changelog or release notes?

As for myself, I don't use CHANGELOG file these days and almost exclusively use GitHub Releases.

There are 3 main reasons for this:

1. Managing hundreds of repositories is getting harder
2. GitHub Releases is getting better
3. CHANGELOG tends to conflict on large projects

Release notes

GitHub has the ability to automatically generate releases notes.

This feature summarizes the pull requets that have been merged with the current version. It is quite useful because it includes a link to each pull request, the name of author, and a list of contributors for that version. If you try to generate this by yourself, it's not that easy. Most of all, I like the fact that this feature is officially provided by GitHub.

If you put .github/release.yml, it also generates separate sections according to the labels attached to the pull requests. Since I like the keep-a-changelog-like format, I have prepared these 6 labels:

• add
• change
• deprecate
• fix
• remove
• security

Basically, I add these labels at the time of review, but even if I forget to do so, I can add them before release.

Labels

It's troublesome to prepare these labels on each repository by hand, so I've automated it by using github-label-sync-action. If you put the name, description, and color of each label in .github/labels.yml, it will automatically sync them to GitHub.

Furthermore, I would like to automate the process of preparing this configuration YAML files, so I created r7kamura/github-keepachangelog-template for that and use gitcp to copy it to the current directory.

gitcp r7kamura/github-keepachangelog-template

Workflows

I also use GitHub Actions these days to automate the process of publishing new versions, such as tags and releases. For example, with a npm package, we put the version in manifest.json. I have a workflow that detects the version change and automatically creates a new Git tag, a new GitHub Release, and so on.

Since it is time-consuming to prepare such workflows for each repository, I use Reusable workflows and organize my own workflows in r7kamura/workflows.

This is an example workflow to release my VSCode extension from vscode-ruby-light:

name: release

on:
  push:
    branches:
      - main

jobs:
  release:
    uses: r7kamura/workflows/.github/workflows/vscode-extension-release.yml@main
    secrets:
      vsce-token: ${{ secrets.VSCE_TOKEN }}

Just write this, change the version field in package.json and git push it, and it will automatically create a new git tag, a new GitHub Release with automatically generated release notes, build the extension, and publish it to the VSCode marketplace.

Wrapping up

I wrote about how I manage my release notes.

Release notes are very important source of information for users. However, I understand that it can be difficult to maintain them. I would like to be able to automate it and manage it without incurring costs.