Release notes management
Tags: github, changelog
Published: 2022-08-12 02:27:59

---
title: Release notes management
published: true
description: 
tags: 
  - github
  - changelog
# cover_image: https://direct_url_to_image.jpg
# Use a ratio of 100:42 for best results.
---

How do you manage your OSS changelog or release notes?

![GitHub Releases](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cardnlqg2a8lsx627no3.png) 

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](https://docs.github.com/en//repositories/releasing-projects-on-github/automatically-generated-release-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](https://keepachangelog.com/en/1.0.0/)-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

![GitHub Labels](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hhdlyym1ro8a2v60lz02.png)

It's troublesome to prepare these labels on each repository by hand, so I've automated it by using [github-label-sync-action](https://github.com/r7kamura/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](https://github.com/r7kamura/github-keepachangelog-template) for that and use [gitcp](https://github.com/r7kamura/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](https://docs.github.com/en//actions/using-workflows/reusing-workflows) and organize my own workflows in [r7kamura/workflows](https://github.com/r7kamura/workflows).

This is an example workflow to release my VSCode extension from [vscode-ruby-light](https://github.com/r7kamura/vscode-ruby-light):

```yaml
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.