BacklogのGitリポジトリからチェンジログを生成するツール「gbch」 を開発したので、開発の動機や使い方についてご紹介します。(Backlogの公式ツールではありません）
目次
要約
- BacklogのGitリポジトリのコミットログからプルリクエストを介したマージコミットを収集してチェンジログを自動生成するツールです。
- GitHubリポジトリでチェンジログを生成するツールの github.com/Songmu/ghch をフォークしてBacklogの仕様に合せて改造しました。（gbchのチェンジログはghchで生成しています）
- Markdown記法とBacklog記法の出力に対応しています。
- 基本的にはSemver（Semantic Versioning）に沿った形式のタグに対応しており、オプションでタグのプレフィックスを任意の文字に変更できます。
- オプションでヌーラボアカウントと連携しているユーザのユニークIDを出力できます。
出力されるマークダウンテキストの例
| # Changelog ## [1.3.0](https://vvatanabe.backlog.jp/git/GBCH/gbch-example/compare/1.2.7…1.3.0) (2019-10-19) * Use CharSequence not String as input type for Zxcvbn.measure [#64](https://vvatanabe.backlog.jp/git/GBCH/gbch-example/pullRequests/64) ([SteveLeach-Keytree](https://vvatanabe.backlog.jp/user/SteveLeach-Keytree)) ## [1.2.7](https://vvatanabe.backlog.jp/git/GBCH/gbch-example/compare/1.2.6…1.2.7) (2019-07-23) * remove java.nio.charset.StandardCharsets [#63](https://vvatanabe.backlog.jp/git/GBCH/gbch-example/pullRequests/63) ([vvatanabe](https://vvatanabe.backlog.jp/user/vvatanabe)) |
マークダウンテキストをBacklog上で表示した例
開発の動機
個人的にGitHub上のリポジトリで開発しているライブラリやコマンドラインツールは、オリジンのghchでチェンジログを生成しており、リリースの作業に必要不可欠なツールになっていました。その流れで、業務で使用しているBacklogのリポジトリも同じようなフローで自動でチェンジログを生成できるのではないかと思い、ghchをフォークして改造してみました。
インストール方法
gbchコマンドをインストールする方法を解説します。
Homebrew
MacOSで使用可能なパッケージマネージャであるHomebrewでインストールできます。
| brew tap vvatanabe/gbch brew install gbch |
Go
Go（go1.14+）をインストールしていれば、go getでもインストールできます。
| go get github.com/vvatanabe/gbch/cmd/gbch |
GoBinaries
Goをインストールしていなくても、gobinaries.comにcurlでリクエストすることで簡単にインストールできます。
| curl -sf https://gobinaries.com/vvatanabe/gbch/cmd/gbch | sh |
Github Release Page
ビルド済のバイナリはGitHubのリリースページからOS毎にダウンロードできます。ダウンロード後、パスが通ったディレクトリに配置してください。
基本的な使い方
基本的に実行方法とオプションはオリジンのghchと同じです。ここでは、ghchのREAMDMEに沿って説明します。
Synopsis
| gbch -r /path/to/repo [–format markdown] |
Options
| -r, –repo= 対象の Git リポジトリのパスを指定します (デフォルト: .) -g, –git= Git コマンドのパスを指定します (デフォルト: git) -f, –from= 出力するチェンジログの始点のリビジョンを指定します -t, –to= 出力するチェンジログの終点のリビジョンを指定します –latest 最新のバージョンのチェンジログのみ出力します –apikey= Backlog API キーを指定します –remote= 対象の Git リポジトリのリモート名を指定します (デフォルト: origin) -F, –format= 出力するチェンジログのフォーマットを指定します（値: json, markdown , backlog） -A, –all すべてのバージョンのチェンジログを出力します -N, –next-version= 次のバージョン（最新のバージョンから現在までの変更）に名前を指定して出力します -w チェンジログをファイルに書き込みます –show-uid ヌーラボアカウントのユニークIDを含めて出力します (ヌーラボアカウントと連携しているBacklogユーザのみ) |
Backlog API Key
gbch は内部でBacklog API v2を使用しているので、Backlog APIのキーが必須です。以下のとおり、コマンドラインオプションと環境変数で指定できます。コマンドラインオプションを優先して読み取ります。
- コマンドラインオプション –apikey
- 環境変数 BACKLOG_API_KEY
依存関係
内部でGitコマンドを使用しているため、git 1.8.5以上がマシンにインストールされている必要があります。
使用例
いくつかの使用例を、オリジンのghch の使用例を参考に記載しています。
最新のバージョンから現在までの変更をマークダウン形式で出力する
| gbch -F=markdown |
最新のバージョンから現在までの変更に名前を付けてマークダウン形式で出力する
| gbch –format=markdown –next-version=v1.3.0 |
最新のバージョンから現在までの変更に名前を付与してマークダウン形式でファイルに追記する
| gbch -w –format=markdown –next-version=v1.3.0 |
最新のバージョンの変更のみ出力する
| gbch -F markdown –latest |
すべてのチェンジログをマークダウン形式で出力する
| gbch –format=markdown –next-version=v1.3.0 –all |
範囲を指定してマークダウン形式で出力する
| gbch –from v1.2.7 –to v1.3.0 |
改造したポイント
BacklogのGitで使用するにあたって改造したポイントについて解説します。
Backlogのプルリクエストのマージコミットを拾う
コミットメッセージをもとにプルリクエストを介したマージコミットかどうか正規表現で判定しているのですが、Backlogのマージコミットの文言をマッチさせるように変更しました。
プルリクエストの詳細情報をBacklog APIで取得する
プルリクエストを介したマージコミットからチェンジログを出力する上で、プルリクエストのタイトルや作成者の情報が必要です。gbchはBacklog API v2を使用して、それらの情報を取得しています。そのため、gbchの実行にはBacklog APIのキーが必要です。
Semver のプレフィックスに任意の文字を指定する
基本的にv1.0.0や1.0.0のようなSemver形式のGitタグをもとにチェンジログを生成します。
実際の業務では単一のリポジトリで複数のサブプロジェクトを持たせるようなリポジトリ運用をしている場合、foo-1.0.0、bar-1.0.0、baz-1.0.0のような独自のプレフィックスをタグに付与するケースがありました。
そのため、サブプロジェクト毎にチェンジログを集約できるように、任意の文字をプレフィックスとして指定できるようにしました。
以下はプレフィックスとして foo-を指定してCHANGELOG_FOO.mdに出力する例です。
| gbch -w -F=markdown –ver-prefix=foo- -N foo-1.1.8 CHANGELOG_FOO.md |
Backlog 記法で出力する
Backlogはテキスト整形のルールとして、Markdown記法と独自のBacklog 記法をサポートしています。gbchで出力するチェンジログもgbch -F=backlogでBacklog記法を指定できます。
以下のようにBacklog記法を設定したプロジェクトの課題でもテキスト整形が可能です。
プルリクエストを作成したユーザに紐付くヌーラボアカウントのユニークIDを出力する
プルリクエストを作成したユーザがもしヌーラボアカウントを使用している場合、オプションの–show-uidを付与することで、ユニークIDをプルリクエストにリンクに紐つけて出力できます。
例えばチームで開発している製品の場合、新しいバージョンのリリース前に、前回からのチェンジログを元にどのような変更がリリースされるのかチーム内に共有することがあるかと思います。
その際に、ヌーラボアカウントのユニークIDを出力しておくことで、Typetalkを使用してチェンジログを共有した場合に、@メンションで通知できます。これでプルリクエストの作成者に事前共有しやすくなります。
以下は TypetalkのBotからgbchで生成したチェンジログを投稿した例です。各プルリクエストの右端に@メンションが付与されています。
謝辞
GitHubとBacklog、対象のサービスは違いますが、gbchはghchが提供してくれた仕組みをほとんどそのまま活用できました。実際の業務でも一部の機能のリポジトリでリリース前に使用しています。
コードやアイディアに誰でも触れることができて、新たな価値を付加する自由があるオープンソースソフトウェアと著者(@songmuさん)に、あらためて感謝します。ありがとうございました。
参考
- https://songmu.jp/riji/entry/2016-05-10-ghch.html
- https://github.com/Songmu/ghch
- https://semver.org/
こちらもオススメ：
プロジェクト管理とは？目的や項目、管理手法について徹底解説！ | Backlogブログ
プロジェクト管理の基本や主な項目を紹介。CCPMやWBSなどのプロジェクト管理の代表的な手法やプロジェクト管理全体の流れを解説。これからプロ…
backlog.com