TL;DR: issue はテンプレート化すると良いです
皆さんちゃんと issue 作っていますか？
僕はそう言われるとちょっと気まずいです。
雑な issue
まずは弊社のリポジトリの中から雑な issue の例を上げてみたいと思います(勝手に拝借しちゃってごめん...)。
一目見ただけで沢山突っ込みどころありますよね！
- どの画面での遷移アニメーションだよ！
- そもそも遷移アニメーションってなんだよ！
- 再現手順は？
- どのバージョンで発生するの？
- バグならバグってラベル付けて！
- 誰かにアサインしようよ！
- 誰もこれ見て状況を把握できねぇよ！！！
という感じで大量に突っ込めます。
issue って便利なのでちょっと思いついたアイディアをタイトルだけメモみたいな感じで書いて作ってしまったりすることがあります。
それを後で見返すと、「この時何考えてたんだっけ..？」となったりします。もちろん他人が見ると完全に意味不明です。
また、普段はちゃんと issue を書いていても、忙しいときなど後でちゃんと書こうと思ったつもりで作ったけどそのまま放置されてしまうパターンも有ると思います。
どうしよう
完璧な解決方法は無いですが改善する方法はあります。
その1つが issue のテンプレート化です。
GitHub Issueはテンプレート化で、綺麗に書かせる！ で紹介されているように GitHub の issue を開くときの URL にパラメータを渡すとそれが最初から入力された状態でページが開くので簡単に issue のテンプレートを作ることが可能です。
issue を作る度にいちいちテンプレートをメモってあるページを開いてそれをコピペして... とか面倒くさいですがこの方法なら、リンクをブックマークしておくだけで何時でも簡単に issue を作ることができます。
弊社ではこのようにリポジトリの中に CONTRIBUTING.md を配置してここから簡単にブックマークできるようにしています。
これだけだと、先ほど挙げた記事の紹介だけで終わってしまうので、実際弊社でどのようにテンプレートを作っているのかについて書きたいと思います。
より良いテンプレート
例えば弊社で使っている不具合報告のテンプレートはこんな感じです。
### 概要
- 不具合の内容
- iOS のバージョン
- 端末の種類
- 再現性ある or たまにしか起きない
- 報告ツイートなどあれば貼り付ける
### 再現方法
- 一定の手順が必要な場合は書こう
---
人にアサインしよう
このテンプレートは「最小限のことしかテンプレートに書いてないと、恐らく最小限のことしか書かなくなってしまう。」という考えから作られています。
必要そうなものがあったらモリモリ書いていこうという感じです。
こうすることで、 issue を作った時に「あれも書いておこう」、「これも書いておこう」とスムーズに項目を書くことができます。
これらの項目が無いと「何を書けばいいんだっけ？」と項目を思い出すところから始まってしまい非効率です。
先ほどのテンプレートを見ると一番最後の行に 人にアサインしよう と書いてあります。
これは issue を誰にもアサインしないと責任者が不在の issue ができていつになっても消化されなかったり、挙げ句の果てには同じ内容の issue が作られて大変悲しいことになるのを防ぐためのルールです。
この事についてテンプレート化以外のアプローチとして紹介したいと思います。
テンプレートだけじゃなくてガイドラインも作ろう
弊社にはテンプレートよりも偉い文章(憲法と刑法みたいな関係)として開発ガイドラインという物があります(gist で公開しています)。
開発ガイドラインの issue の項目を見ると 人にアサインしよう と太字で書いてあります。
これが issue を立てるときに一番大事にしているルールです。
しかし、常に人にアサインできるわけではありません。
そのような状況を開発ガイドラインでは 非開発者が issue を立てるとき という項目で説明しています。
弊社ではユーザーサポートの担当がいて、ユーザーからのバグ報告によりバグの issue を作る場合が良くあります。
しかし、開発者ではないのでそのバグを誰が直すのが一番早いのかなど適任者はすぐに分かりません。
さらに、 issue を立てる度に開発者に聞いて回って誰にアサインすれば良いのかを決めるのも非効率です。
そこで
その場合はとりあえず自分にアサインした後にどこかで開発者側と時間を取って アサインを行いましょう。
Issue を作るごとに開発者側と話し合うと時間を無駄に消費してしまうので 複数個作ることが想定される場合はまとめて話し合いを行えるようにしましょう。
というルールを設けています。
まとめ
- テンプレートを作ろう
- できればガイドラインも作ろう
これらの文章を作る上で気をつけてほしいことがあります。
弊社ではこれらの文章はみんなで話し合って、必要性を共有したうえで作っています。
もしこれが、誰かの思いつきで一方的に作って、一方的にみんなにやらせるというようなものならなんの意味もないものになってしまいます。
是非、メンバーで話し合ってみんなで作ってみてください。
何故みんなで作ったほうがいいのか？というふわふわした内容に関してはこちらの記事を呼んでみてください。