かっこいいバグレポを書こう！

もう春ですね。新人さんたちに向けてポエムを書きたくなる季節です。
というわけで不具合報告の書き方をまとめてみました。

ソフトウェアには不具合がつきものです。これから仕事で四六時中コードを書くようになると、自分たちで作っているシステムや、利用しているOSSライブラリに不具合を見つけることがあります。
そんなときツボを押さえた不具合報告をすると、こいつ...できる！感を上げることができます。

心構え

「バグを憎んで人を憎まず」

これは私が新人時代に上司から言われた言葉です。
こんなしょぼい不具合入れやがってと思うこともあろうかと思いますが、ぐっとこらえて、淡々と事実をつづりましょう。時折クスッと笑えるネタを仕込むのもいいかもしれませんね。（やりすぎると鬱陶しいだけなので注意してください）
お前間違ってんぞと指摘されると、イラッとしたり不安に思ったり、人は多少なりとも心にダメージを受けるものです。全く気にならないという強い人もいますけども、不必要に煽る必要もないでしょう。

そうそうこの、事実をつづるというのも重要なポイントです。

また、セキュリティに関する内容の場合はいきなりおおっぴらにせず、メンテナーや上司に直接連絡をとってみましょう。外部のソフトウェアで、コミュニケーションが不安な場合は JPCERT にお願いしてしまうのも良い選択だと思います。

で、何を書けばいいの？

では具体的に見ていきましょう。

タイトル

1行で問題を簡潔に表しましょう。

「500エラーが発生する」これはNGです。何が問題なのかわかりませんね。
例えば「えんぴつをカートに入れると500エラー」のように、何をして、どうなったかを書くと良いと思います。

また、一意であることも重要です。不具合修正の担当者が週報などを書く際に、報告がしやすくなるなど、コミュニケーションがしやすくなります。不具合報告の重複を防ぐことにもつながります。

概要

数行を目処に、タイトルよりも詳しく、問題の概要を日本語で書きましょう。

typoなど、単純な不具合の場合は「表題に同じ」などとしてしまっても大丈夫でしょう。

再現手順

確実に実際の手順を余すところ無く書きましょう。
Webアプリやスマホアプリの場合はスクリーンショットを動画で添付するのも有効です。

これいらんやろという手順が実は必要だった、ということもありますので省略せずに書きましょう。（流石に ls とかは不要だと思いますけどね）

期待した結果

報告をしても相手が不具合と認識しないケースもあります。また逆に、自分が期待した結果が間違っていて、実は正しい挙動だった、ということもあります。
自分がどういう結果を期待していたかを伝えることでコミュニケーションの失敗を防ぐことが出来ます。

実際の結果

ログやコンソールの出力を極力省略せずに貼り付けましょう。

Webサービスの場合、実際に操作した日時を伝えると感謝されることもあるでしょう。
サーバ側のログを追えるようになるので、問題の解決につながることがあります。

実行したバージョン

OSやブラウザのバージョン、アプリのバージョンを明記しましょう。
場合によってはCPUアーキテクチャも明記したほうがいいかもしれませんね。M1 mac でのみ再現する不具合もこれから増えてきそうです。

再現頻度

毎回発生するのか、数回に１回なのか、１回だけ発生してその後再現しないのか。

タイミングや環境に依存する不具合、相手の手元で再現しないこともあります。そんなとき再現頻度のヒントがあると、解決の手助けになります。
また、取り組む優先度の判断にも役立ちます。再現性が低いなら後回しにしよう、とか。

テンプレート

上記を抽出したリストです。プロジェクトによっては既にテンプレートが定められているケースもあります。その場合はその指示に従いましょう。

#### 概要
#### 再現手順
#### 期待した結果
#### 実際の結果
#### 実行したバージョン
#### 再現頻度