雑文発散

▼ [PHP] PHP の readmegen で ChangeLog の自動生成を実験してみた

PHP の readmegen というツールに出会った。簡単に言うと「README.md 内に記述する ChangeLog の内容を commit log から自動生成する」というもの。

全ての commit log を抽出する訳ではなく、先頭に feature: だとか bugfix: だとかのキーワードが入ったログのみが対象となる。また、そのキーワードごとにグルーピングしてファイルに書き出される。

例えばこんな感じの commit log になる。

• feature: Implemented #1
• bugfix: シンタックスエラーを修正。

インストールは Composer から行なう。 global にインストールしても良いけど、ローカルに入れるほうが好みなのでそうしてみた。

% composer require fojuth/readmegen:1.*

これでプロジェクト内の ./vendor/bin/readmegen を叩けば実行できるようになる。

コマンドの引数は（ドキュメントからの丸コピだけど）こんな感じになる。

% readmegen --from TAG --to TAG --release RELEASE_NUMBER --break BREAKPOINT

--from TAG から --to TAG までの間の commit log を --release RELEASE_NUMBER として ChangeLog を生成する。--break BREAKPOINT というのは「BREAKPOINT のキーワード以下にテキストを差し込む」という意味になる。

例えば --break "## ChangeLog" という指定をすれば、下記の [Insert Here] のところ（## ChangeLog の後ろ）に差し込まれる。この指定がないとファイルの先頭に差し込まれるみたい。

## Sample Project

This is Sample project.

## ChangeLog

[Insert HERE]

また、TAG は、git tag で名付けたタグはもちろん使えるし、50b8125 のようなハッシュ値を指定しても良い。--to が HEAD でよければ省略も可能。

設定ファイルとして readmegen.yml も使える。その内容を見ればだいたいどう動くかは想像できるんじゃないかな。

vcs: git
format: md
issue_tracker_pattern: http://some.issue.tracker.com/\1
break: "## Changelog"
output_file_name: "README.md"
message_groups:
  Features:
    - feature
    - feat
  Bugfixes:
    - fix
    - bugfix
  Documentation:
    - docs
  Refactoring:
    - refactoring

commit log に #nn などの Issue 番号を含めておき、上記の issue_tracker_pattern を適切に設定しておけば、ChangeLog に含まれる #nn からその Issue へのリンクを自動生成もしてくれる。

ちなみに vcs: git とかあるけど、今のところ git 以外の VCS には対応していない。拡張しやすそうなコードにはなっているので、必要に応じて追加すれば良さそう。

実際にどんな感じになるのか知りたかったので、サンプルのプロジェクトを作って試してみたので、気になった人は見てみると良いかも。

• https://github.com/suzuki/readmegen-sample

全ての commit log ではなく、特定のキーワードを付けたログが対象になり、しかもそれがグルーピングされて生成されるというのは見やすくなって良い。

一方で、commit log を適切に運用できていないと、途端に「抜け」が発生してしまうのが難かなぁ。例えば適切ではない commit log をコードレビュー時などに見つけたとして、「その commit log は直して」という運用は、とてもやりにくそうな気がする。

ところで、なんでこの readmegen を見つけたかという話を少し。少しというか、こっちが日記の本編だ。

いまのチームではスクラムもどきを導入していて、「このスプリントにやったことリスト」みたいなのが欲しいという要件が出てきた。

各スプリントでのスプリントバックログがそれじゃん？という話なのだが、ウチのバックログは Trello で管理していて、見た目とか使い勝手は良いのだけど、一覧性だとテキストのリストには敵わない。

じゃあ、Trello の API を使って、終了したタスクのリストを作ればいいかな？とか考え始めた時に、この記事に出会った。

• WIPなPull RequestによるOSS開発とoctoreleaseの相性がいいことに気づいた

この記事では octorelease が紹介されていて、これこれ、こういうのだよ！と思ったんだけど、手元のプロジェクトが PHP ベースなので、このためにプロジェクト内に Rakefile とか置くのはどうなのかなーとも思った。

PHP で似たようなのないかなーと検索した結果、出会ったのが readmegen だった。octorelease とは用途が違ったけど、これはこれで面白いのかも？と実験したのであった。