2015/08/10

プログラマに伝えるためのIssue（バグレポート）の書き方【GitHub編】

GitHubでアプリケーションを公開してから、Todoの代わりとしてIssueを書きたくなった。
ということで、プログラマに伝えるためのIssue（バグレポート）の書き方をまとめてみた。
ついでに、前職の炎上プロジェクトで多くのバグ報告を書いて、対応してきたので、そのときの経験も踏まえて書いておく。

Title

タイトルを書くときのポイントは次のとおり。

簡潔であること
バグの内容が把握できること
設計要素の名称を書くこと
発生した状況がわかること

例：【伝票検索画面】キーワードを入力し検索ボタンを押下するとエラー

タイトルの先頭に【優先度】や【機能名】のように、隅付き括弧で目印を書くことが多い。

Comment

「Leave a comment」には、バグの詳細情報を書く。

問題の内容（現象）

複数のバグをひとつのIssueにまとめないこと
どのようなバグが発生したのが、できるだけ具体的に書くこと
エラーのスクリーンショットやログを添付すること
「バグ」と「要望」を切り分けてから書くこと
共有された正しい用語を使うこと

バグが複数まとまってると、管理が難しくなったり、クローズできなくなったりと不都合が多い。そのため、「1Issue 1バグ」で書くこと。

「バグ」と「要望」を切り分ける方法は、客観的に考えること。仕様書どおりに動かなければ「バグ」、仕様書にも書いてないけど『こうなってほしい』とか『こうあるべき』というのは「要望」。
それらの報告をあげるなというわけではなく、「要望」ですよということを明記すべき。

共有された正しい用語を使うことは曖昧さをなくすためにも重要だ。

もし用語が共有されていないと「ページ上部のメニューが並んでいるバーみたいなの」という説明になり、人によっては表現が変わってくるだろう。

用語が共有されていれば「ナビゲーションバー」と説明するだけですむ。表現のブレも気にしなくてよい。

実行環境

OSやブラウザ、アプリケーションのバージョンを明記すること

これがないと、報告者環境ではエラーになるのに、プログラマの環境ではエラーにならないという事態になってしまう。

再現手順

できるだけ詳しく書くこと

期待される結果

本来どうあるべきかを書くこと
わかれば、何が原因なのかを書くこと

例：
## 内容

伝票検索画面の「伝票内容」にキーワードを入力し、検索ボタンを押下すると「Error:xxx エラー」というエラーメッセージが表示される。

## 実行環境

* Windows 7 64bit
* Chrome 44
* App release v1.2.3

## 再現手順

1. メニューから伝票検索画面を表示する
2. 「伝票内容」に全角英数字を入力する
3. 「検索ボタン」を押下する

## 期待される結果

エラーが表示されず、入力した伝票内容と一致する伝票が表示される。
半角英数字を入力した場合は正常に検索ができるので、全角英数字の入力を制限するか、検索処理で半角に変換する。

Labels

bug

バグ報告をするときに使う。

→ 修正したらクローズ

duplicate

過去に報告されているIssueと重複しているときに使う。
※ バグ報告者は使わない。

→ 重複先のIssueにリンクしてクローズ

enhancement

機能追加の要望や、改善してほしいときに使う。

→ 実装したらクローズ

invalid

Issueの内容が間違いである（仕様通り）であるときに使う。
※ バグ報告者は使わない。

→ 対処しない理由を書いてクローズ

question

質問・確認したいときに使う。

→ 質問・議論の答えがでたらクローズ

wontfix

認知しているけど対処しないバグのときに使う。
※ バグ報告者は使わない。

→ 対処しない理由を書いてクローズ

Milestone

マイルストーンを指定することで、「いつまでに何をやらなければならないのか」が集計され、一覧で見ることができる。
タスク管理や進捗管理として使われる。

例えば、「Version2.0 Release」というマイルストーンを指定すれば、Version2.0をリリースするまでにどれだけのタスクが残っているかを確認することができる。

Assignee

Issueを誰に割り当てるかを指定する。
たいていの場合、バグ報告者は使わない。

Issueをクローズするコミットメッセージ

コミットメッセージを次のようなフォーマットで記述すれば、コミット時に自動的に該当Issue（ここでは#12）がクローズされる。

fix #12
fixes #12
fixed #12
close #12
closes #12
closed #12
resolve #12
resolves #12
resolved #12

さいごに

Issueを書く上で重要なのでは、プログラマの立場になって書くこと。

プログラミング経験のない人が書いたIssueは、あいまいなことが多い。
「なぜかエラーがでた」とか「○○になると"思う"」とか「異常終了した」だけとか...

報告者本人にはわかっていても、対応するプログラマにとってはわかりづらかったりする。

製品を作り上げていくのは、プログラマだけじゃない。
テスターもお客様も、互いに協力しあって作り上げていくものだ。
だから、バグがでたからとイライラせずに、なるべく詳しく、できるだけわかりやすく"伝わるIssue"を書いてほしい。

余談だが、GitHubの詳しい使い方は「GitHub実践入門」がオススメ。
「Issueの書き方」に関しては詳しく書かれていないが、「Issueを使ってできること」についてはスクリーンショットも交えて紹介されている。