GitHubで使えるリリースノート(ChangeLog)自動生成ツール3選(2021年版)

19728 ワード
GitHub release-note ChangeLog GitHubActions CICD GitHub テキストリンク

はじめに

皆さんはソフトウェアのリリースノート(ChangeLog)をどのように作成・運用されているでしょうか？
もし「作成していない」「手動で作成している」ということであれば、作成にはかなりの工数がかかり、抜け・漏れが発生する可能性がございます。本記事ではそうしたリリースノートの作成の工数を削減し、抜け・漏れを減らすを方法として、GitHubで利用できるリリースノート(ChangeLog)自動生成ツールをご紹介いたします。

対象読者

  • リリースノートの作成を自動化して楽したいと考えている方々

リリースノート自動生成ツールの紹介

実行環境
Windows (WSL2 Ubuntu-20.04)

1. Spring IO github-changelog-generator

1.1. 概要

Javaのフレームワークとして有名なSpringのChangeLog生成ツール。
Githubのissueとマイルストーンを指定し、ChangeLogを作成します。
コミットメッセージに依存せず、GitHubのIssuesとMilestoneから出力するシンプルな作りです。

GitHub : https://github.com/spring-io/github-changelog-generator

1.2. こんな方にオススメ

  1. GitHub issueにてlabelとマイルストーンを利用しているプロジェクト
  2. 過去にリリースしたリリースノートも作成したい
  3. 特定のマイルストーンのみ出力したい
  4. コミットメッセージにルールを作りたくない

1.3. 実行方法

docker run -it --rm -v $(pwd):/home \
  springio/github-changelog-generator:0.0.5 \
  java -jar github-changelog-generator.jar \
   --changelog.repository=[オーナー名]/[プロジェクト名] \
   --github.token=[GITHUB_TOKEN※] <マイルストーン> /home/ChangeLog.md

※GITHUB_TOKENの払い出しについて
GitHub APIを50回/時間の制限を解除するため、パーソナルアクセストークンページから払い出しておきましょう。(repoへのアクセス権限のみあればOKです)

コマンド実行

このファイルは /homeにマウントしたカレントディレクトリ$(pwd)に出力されます。

1.4 出力結果

markdownファイル

GitHubの場合以下のように出力されます
ForkしたリポジトリからのMergeされた場合はContributorsにユーザも付与されます。素敵ですね。

2. github-changelog-generator

2.1. 概要

Ruby製のChangeLog生成ツール。
オプションが豊富で柔軟な出力が可能。サマリ機能、未リリースを出力する機能がある。

GitHub: github-changelog-generator

2.2. こんな方にオススメ

  1. コミットメッセージにルールを作りたくない
  2. オプションにて出力内容制御したい方(細かなオプションによる制御が可能)
  3. テンプレート機能を利用しない方
  4. Rubyのプロジェクトへ組み込みたい方（Rakefileへ設定を組み込むことが可能）

2.3. 利用方法

docker run -it --rm -v "$(pwd)":/usr/local/src/your-app ferrarimarco/github-changelog-generator -u [オーナー名] -p [プロジェクト名] --token [GITHUB_TOKEN※]

※GITHUB_TOKENの払い出しについて
GitHub APIを50回/時間の制限を解除するため、パーソナルアクセストークンページから払い出しておきましょう。(repoへのアクセス権限のみあればOKです)

コマンド実行

↓

このファイルは /usr/local/src/your-appにマウントしたカレントディレクトリ$(pwd)に出力されます。

2.4 出力結果

3. conventional-changelog / semantic-release

3.1 概要

JavaScript製のChangelog作成ツール。
atomやvscodeなどのIDEにも対応している。
ChangeLogの作成以外にもGithubリリースの作成、コミットメッセージのlint(解析)、コミットメッセージの規制など様々な機能が搭載されております。

3.2. こんな方にオススメ

  1. ローカルリポジトリで動作させたい
  2. コミットメッセージをルール化したい( デフォルトでは"Angular Commit Message Conventions" が採用されております)
  3. 設定ファイルを用いて細かく設定したい
  4. nodejsプロジェクトで開発ツールとしても利用したい(Gitフックによるコミットメッセージの制御、コミットメッセージのLint機能など)

CI/CDのリリースワークフローへ組み込む場合はsemantic-release を利用しましょう。とにかく多機能！

Github : conventional-changelog

3.3. 利用方法

# Install conventional-changelog-cliをインストールする
npm install -g conventional-changelog-cli

# ChangeLogを作成するgitリポジトリへ移動する
cd repo

# 実行する(初回実行時はすべて出力する)
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

# 実行する(追加処理)
# conventional-changelog -p angular -i CHANGELOG.md -s

3.4 出力結果

今回はangular にて実行しました。

番外編. git-chglog

Go製のChangeLog作成ツール。
マルチOSに対応してバイナリのみで動作可能。

GitHub : git-chglog
製作者のページ: Go製のCHANGELOGジェネレータを作った

残念ながら：failed to get git-tag: exit status 128 エラー

Ubuntu20-04(WSL2にて起動)にてエラーが発生
PATHに/usr/local/git-coreを通してgit-tagを実行できるようにしたものの事象を解決にはいたりませんでした。
本事象はgit-chglog#23として登録済み。CI/CDで使うにはセットアップが容易（ダウンロードするだけ）なので今後に期待したいです。

応用編：CI/CDツールと連携してGithubへreleaseする

上述ではリリースノートを自動生成するツールについてご紹介させていただきました。
次はこの機能をCI/CDツールに組み込んで自動化し、Githubのreleaseへ登録します。

GitHub releaseとは？

GitHubにはリリースしたアプリケーションのリリースノート・ソースコード・バイナリを表示する機能です。

前提

今回、本機能を実現にSpring-ioのgithub-changelog-generatorを利用します。
そのため、以下のルールで運用したいと思います。

  • ChangeLogの作成はIssuesから取得、作成する
  • Issuesにはマイルストーンが設定され、タグと連動している

集計対象

spring-ioのデフォルトの仕様に準拠したものとします。（※カスタマイズ可能です）

アーキテクチャ

tagをpushしたら対象マイルストーンに設定されたIssuesからChengaLogを作成しReleaseへ登録する。またソースコードもzipファイルへ圧縮し、アップロードする。

リリースノートの作成

1. 前提

Github Issueにマイルストーンが設定すること

マイルストーンの作成

マイルストーンの関連付け

マイルストーンがクローズされていること

2. GitHub Actionのコードを作成する

name: GitHub-auto-release

on:
   push:
     tags:
       - 'v*'

jobs:
  release:
    name: Create Relaese
    runs-on: ubuntu-latest
    steps:
      # ソースコードをチェックアウト
      - name: Checkout
        uses: actions/checkout@v2
      # タグバージョンを取得する
      - name: Get Tag Version
        id: get-version
        run: echo "::set-output name=tagVersion::${GITHUB_REF##*/}"
      # Javaのセットアップ(spring-io/github-changelog-generator 実行用)
      - name: Set up JDK
        uses: actions/setup-java@v1
        with:
          java-version: 11.0.x
      # リリースノート(CHANGELOG.md) の出力 ★本日の記事にて紹介した機能
      - name: Create Release Note
        id: create_relase_note
        run: |
          wget -q -O github-changelog-generator.jar https://github.com/spring-io/github-changelog-generator/releases/download/v0.0.5/github-changelog-generator.jar
          chmod +x github-changelog-generator.jar
          java -jar github-changelog-generator.jar \
              --changelog.repository=${GITHUB_REPOSITORY} \
              --github.token=${{ secrets.GITHUB_TOKEN }} \
              ${{steps.get-version.outputs.tagVersion}} ./CHANGELOG.md
      # GitHubへのリリース
      - name: Create release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{steps.get-version.outputs.tagVersion}}
          release_name: Release ${{steps.get-version.outputs.tagVersion}}
          body_path: ./CHANGELOG.md
          draft: false
          prerelease: false
      # GitHubへAssetをアップロード(今回はtarget/CHANGELOG.mdをアップロードする)
      - name: Create Release Asset
        run: |
          mkdir target
          mv CHANGELOG.md target/CHANGELOG.md
      - name: Upload Release Asset
        id: upload-release-asset
        uses: actions/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ steps.create_release.outputs.upload_url }}
          asset_path: ./target/CHANGELOG.md
          asset_name: CHANGELOG.md
          asset_content_type: application/txt

3. 実行結果

3.1 tagを登録する

# masterブランチへv0.0.1というタグを設定し、リモートブランチへpushします
git tag v0.0.1 master
git push origin v0.0.1

3.2. GitHub Actionが起動し、GitHubへリリースされる

4. サンプルリポジトリ

上記は以下のリポジトリで実現されております。
https://github.com/yukiusa/github-action-auto-release-sample

まとめ

今回はリリースノート(ChangeLog)自動生成ツールとして3つ紹介しました。
各ツールの導入難易度としては以下の通りでございます。

# 導入難度 プロダクト 用途
1 spring-io/github-changelog-generator GitHub Issuesのみで手軽に運用したい方
2 github-changelog-generator/github-changelog-generator リリースノートの出力内容を細かく制御したい方
3 conventional-changelog コミットメッセージのルールも作り、プロジェクトツールとしても利用したい方

さいごに

いかがだったでしょうか？

  • IssueのlabelやMilestoneを活用する
  • コミットログにルールを用いる

この2つのアプローチによりリリースノートの自動生成を可能とします。

どのように管理するかはプロダクトオーナー次第となりますが、
リリースノート(ChangeLog）作成を自動化することで以下のことが期待できます。

  • 工数を削減
  • 記述の抜け漏れを低減
  • コミュニケーションを円滑化

今後のプロジェクト/プロダクトの改善活動の一つに取り入れてみてはいかがでしょうか？
最後まで読んでいただきありがとうございました。