Gaiax Advent Calendar 2016 ２日目、~~ギフハブ~~ GitHub のテンプレートについて。

GitHub のテンプレート機能

プロジェクトコードのホスティングサービスとして GitHub を利用している IT 企業は多いと思うし、Gaiax でも活用している。

そんな GitHub に今年の２月に派手ではないがとても便利な機能が追加された。リポジトリのルートに .github というディレクトリを掘ってその中に ISSUE_TEMPLATE.md や PULL_REQUEST_TEMPLATE.md といったファイルを置いておくと、Issue や Pull request を作成する際にテンプレートを表示することができる。

github.com

この機能すごく便利で、今まで

◯◯が××になっていたので修正した

みたいな１行しか説明ない雑なプルリクエストが投げられると

それを直さないと誰がどう困るの
原因はなんだったの
なぜその変更で修正されるの

などなど、いちいち聞き返さなければいけなくてレビューしづらいことこの上なかったのが、テンプレートを用意することによって予め書いてもらいやすくなる。

どういうテンプレートにするか

いざテンプレートを用意したとしても、知りたい内容をちゃんと織り込んでおかないと結局また質問する羽目になってしまう。

「何が言いたいの？」というバグ報告避けに「期待する動作」「実際の動作」「再現手順とコード」みたいなIssueテンプレを用意したら、「期待する動作：ナイスなドキュメントが読める」「実際の動作：ナイスなドキュメントが無い」みたいなIssueが登録されて、違うそうじゃない
— INADA Naoki (@methane) November 22, 2016

ちゃんとしたテンプレートを用意したいけど、こういうの毎回考えるの面倒じゃん？ベストプラクティスみたいなのが欲しいなー、と。

今は少ない頭を振り絞って考えたテンプレートで運用しているんだけども、どうもまだ「ベスト」という感じがしない。もっと改善の余地がある気がする。

つまりこのエントリの趣旨としては、自分のチームのテンプレート晒すから「これだとここ不便じゃない？」「ウチはこうしている」みたいなレスポンス欲しいなーーー |дﾟ)ﾁﾗｯ という感じです。

各位よろしくお願いします。

Pull request テンプレート

まずはプルリクエストのテンプレートから。

<!-- あくまでテンプレートなので必ずしもすべての項目を埋めなくてよい -->

# 概要
<!-- 変更の目的 もしくは 関連する Issue 番号 -->

# 変更内容
<!-- ビューの変更がある場合はスクショによる比較などがあるとわかりやすい -->

# 影響範囲
<!-- この関数を変更したのでこの機能にも影響がある、など -->

# 動作要件
<!-- 動作に必要な 環境変数 / 依存関係 / DBの更新 など -->

# 補足
<!-- レビューをする際に見てほしい点、ローカル環境で試す際の注意点、など -->

 は内容を例示するコメントとして使えて良い。消し忘れたとしても HTML に変換された際には見えなくなるので便利。

 はチーム内で合意が取れてればわざわざテンプレートに書かなくてもいいかなと思う。この一文があるせいで概要以外埋めてないプルリクエストもたまに上がってくるので微妙かもしれない。

Issue テンプレート

続いて Issue のテンプレート。

<!-- あくまでテンプレートなので必ずしもすべての項目を埋めなくてよい -->

<!-- 要望のテンプレート -->
# 概要
# 目的
# 提案内容
# タスク
- [ ] 細かいタスクに分解できているなら書き出す

<!-- 不具合のテンプレート -->
# 概要
# 再現手順
# 修正しないとどう困るか
# 原因
# 修正案

Issue に登録するものってカテゴリに分けられるような気がして。

すごく大雑把に分けて「要望」と「不具合」かな、と思った。

これをひとつのテンプレートにまとめてしまうと「知りたいこと」が書ききれずにまた質問しなきゃいけなくなりそうだし、かといってこれ以上細かくするとテンプレートが巨大になってしまうので、これくらいがいい塩梅なんじゃないだろうか。

このテンプレートを使ってみた感想

すべての項目を埋めなくてよい を入れておくとたまに雑な Issue / PullReq が作られちゃう
- でも Issue とかカジュアルに作って欲しいし、項目埋めるの必須にしたくない
Issue を「要望」「不具合」に分けたのいい感じ
- 作るたびに片方削除するのちょっと手間だけど、そんなに気にならない