こんにちは、フロントエンドエンジニアのいなばです。

案件の開発終盤、こんなことが起きていませんか？

1. 納品が近づき、プロジェクトメンバーで一斉に検証作業を始める
2. 各々バグを見つけ次第、issueを立てていく
3. さあ、バグをかたっぱしから片付けていきましょう

しかし、蓋を空けてみると……書き方の悪いissueが乱立！
バグの内容を把握するのに時間がかかる！

結局わからないのでissueを立てた本人に聞く→結果的にコミュニケーションコストが増える……。コミュニケーションコストを減らすためのツールなのに、やりとりが何往復もしていたら本末転倒ですよね。

そこで、今回はGithubやbitbucketのissue機能を活用したデバッグフェーズでのタスク管理のコツをご紹介します。

悪いissueと良いissueとは？

そもそも、どんなissueが“悪いissue”なのでしょうか？
例を見てみましょう。（極端な例ですが）

悪いissueの例文

ドキュメントを開こうとしたとき、表計算がクラッシュしてました。確か、表計算は図表を含んでいたような気がしないでもないような。Windowsを使用しています。これは本当によくない問題だし、これは今にでも直すべき問題だよ。ところで、このアイコンは実にむかつくね。こんな醜いアイコンを使い続けるなら、誰もこんなソフト使わないよ。あ、それとオバあちゃんがワープロについて問題があるって。ちゃんと動作しないしないらしい。では。

引用元：Open Office Issue報告ガイドライン
http://openoffice-docj.osdn.jp/tr/translated/bug_writing_guidelines.html

ひとまず分解してみましょう。

• ドキュメントを開いたら表計算がクラッシュした。
  表計算は図表を含んでいたかもしれないし含んでなかったかもしれない。これは本当によくない問題であり、今にでも直すべき。
• Windowsを使用している。
• このアイコンはむかつく。
  こんな醜いアイコンを使い続けるなら、誰もこんなソフト使わない。
• ワープロについて問題がある。
  ちゃんと動作しないらしい。

なんだかふわっとしていますね。
アイコンは別の問題ですし、ワープロの問題はそもそも関係がなさそうです。

また、クラッシュすることの原因に図表を含んでいることが関係しているのかハッキリしませんし、WindowsのOSとアプリのバージョンもわからないので、まずは再現できる環境と手順を調べなくてはなりません。

そして再現できない場合には、issueを立てた人に詳しく聞くことになるでしょう。

良いissueの例文

Win NT4.0(Service Pack5)上で10.13.00ビルドを使用すると、添付した表計算ドキュメントを開くたびにクラッシュします。またLinux(RedHat 6.2)上で同じことをしたら、10.13.00のLinuxビルドを使っても同じことが再現できます。
そのドキュメントから図表を取り除いたら、問題なく開くことができました。

引用元：Open Office Issue報告ガイドライン
http://openoffice-docj.osdn.jp/tr/translated/bug_writing_guidelines.html

こちらも分解してみましょう。

• 添付した表計算ドキュメントを開くたびにクラッシュする。
• Win NT4.0(Service Pack5)、またはLinux(RedHat 6.2)上で10.13.00ビルドを使うと起きる。
• ドキュメントから図表を取り除くとクラッシュしない。

すっきりとしましたね。

これならすぐ修正作業に取りかかることができそうです。

良いバグ報告を書くための3つのポイント

悪いissueを乱立させないためには、

• 問題点
• 再現手順
• 解決法（ゴール）

をプロジェクトメンバー全員に明記してもらえるように、issueの書き方（フォーマット）を決めてしまうのが良いでしょう。

バグレポートフォーマットは、当社のディレクターJackが書いている記事も参考になるかと思います。

エンジニアに分かりやすくバグを報告するバグレポートの書き方

2015.10.01

• 90
• 13

定着するまでに時間がかかるかもしれませんが、コミュニケーションコストを減らすために地道に布教していきましょう。

1. 問題点を明確にする

問題点を伝える際は、以下のことに意識しましょう。

• タイトルを簡潔にする
• 原則として、ひとつのissueに対してひとつの問題を扱う
• 適切な粒度でissueを立てる
• 複数の問題はひとつひとつ分割する

問題は細かくした方が解決が早いです。
問題点が明確に書けないときは、下記2点に気をつけてみましょう。

• 問題が大きすぎないか？
• 複数の問題を扱っていないか？

問題が大きすぎたり複数の問題を扱ったりすると、issueの重複も生まれやすくなりごちゃごちゃします。またcloseもしづらくなり、いつまでも残ってしまうことになりがちです。

2. 再現手順を明確にする

つづいて、他の人も再現できるように再現環境と手順を明確にしましょう。

• 再現する環境を明記する
• 再現手順を明記する
• 再現する場所（URL）を明記する
• キャプチャを載せる

非エンジニアは技術的な難しいことを頑張って書かなくてOKです。
頑張って書いたのにかえってわかりづらくなるのは悲しいですし、箇条書きでも十分伝わるので。

ただし、

• 事実と推測は区別する
• 私情を挟まない

この2点はとても大事なので気をつけましょう。

3. 解決法（ゴール）を明確にする

解決方法を明記してあげたほうがより親切ですが、問題点と再現手順が明確であれば解決法も明確になっているはずです。

さらに効率を良くしよう

さらに効率を上げるために、issueを定期的に巡回して整理しましょう。

特に優先度は状況によって変化していきます。
優先度の指定がみんな“最優先”になっているとラベルとして機能しなくなるので、定期的に適切なラベルに付け替えてあげるとより良いと思います。

1. 悪い書き方のissueを修正する

タイトルや詳細を適切に書き直せる場合は修正しましょう。
不明の場合は、issueを立てた担当者にアサイニーを付け替えて戻します。

2. 重複しているissueは片方を閉じる

重複しているissueを見つけた場合は、片方を閉じてしまいましょう。
その際に閉じるほうのissueに、残すほうのissueへのリンクをつけます。

▼閉じるほうのissue

 
▼残すほうのissue

Githubではコメントに #{issue番号} と入力すると、自動で関連付けをしてくれます。

3. 複数の問題を扱うissueは分割する

ひとつのissueに対してひとつの問題を扱う原則が守られてないissueは分割します。

分割した問題がissue上になければ新しく登録します。
複数の問題を含んでいたissueは、分割したissueへ関連付けをしたら閉じてしまいましょう。

終わりに

いかがでしたか？
みなさんのデバッグフェーズの効率が上がることで、ブラッシュアップなどのクリエイティブな作業により時間が割けるようになると幸いです。

参考

Issue報告ガイドライン
http://openoffice-docj.osdn.jp/tr/translated/bug_writing_guidelines.html