bug-tracking - チケット/バグのフォーマットはどのくらい重要ですか?

Question

バグレポートをフォーマットすることはどれほど重要ですか? それは何を含むべきですか？

通常、バグレポートには次のセクションが表示されます。

再現する手順
私が見るもの
私が見なければならないもの
説明

バグレポートをフォーマットするための最適なソリューションと、その内容を教えてください。

score 3 · Accepted Answer

バグ報告フォーマットガイド

Rawr にあるバグや機能のリクエストを明確に追跡するために、Issue Tracker にバグを投稿する際に、次の情報を提供するようユーザーにお願いしています。

タイトル- これは、バグが属するカテゴリ (モデル固有の場合はモデル、または比較、オプティマイザーなどの高レベル機能) と、問題の簡単な説明の概要を示す必要があります。カテゴリがわからない場合は、そのままにしておいてください。必要に応じて調整します。
説明- これは段落ではなく、何が壊れているか、または機能していないかを簡単に概説する必要があります。
再現手順- その名の通り、問題のバグを再現する手順です。アプリケーションの起動から開始する必要があります。
バージョン番号/追加情報- 実行している Rawr のバージョン、OS、スタックトレース、およびエラーメッセージ。通常、Rawr でのクラッシュ時に生成されるような大きなエラーメッセージは、説明に投稿するのではなく、error.txt ファイルに保存し、Issue に添付する必要があることに注意してください。これにより、問題を修正しようとしている開発者にとって、書式がすっきりし、スクロールが少なくなります。
詳細- ページの右側に、タイプ (問題)、リリース (バージョン番号)、およびコンポーネント (存在する場合) を記入してください。
添付ファイル- 問題を再現するキャラクターファイルを添付してください。

例

タイトル: [アイテムエディター] アイテム編集でクラッシュする
説明:ヘルムアイテムを編集すると Rawr がクラッシュします。
再現する手順：

Rawr を起動
ツール > アイテムの編集
ブラッドファングマスクを選択
敏捷値を112から113に変更
「OK」ボタンをクリック
Rawr がクラッシュすることを確認する

score 2 · Accepted Answer

フォーマットの最終的なポイントは、人々が問題を再現またはデバッグするのに十分な情報を一貫して含めるようにすることです。ある種の形式を強制しなければ、人々は頭に浮かぶものを何でも使用します。ソフトウェア開発プロセスを十分に理解しているよく組織化された人々の場合、関連するすべての情報を自分で含める可能性があります。

一方、多くの場合、組織全体から、またはユーザーから直接、バグレポートを受け取ります。さらに言えば、誰かがただ急いでいて、ガイドとしての標準的な形式がない場合、「アプリケーションが正しく機能していません」などのバグレポートを受け取る可能性があります。一日の終わりに、関係なく報告されている正確な問題が何であるか (どこで、いつ発生し、どのように再現するか) を把握し、デバッグできるようにするために必要な最小限の情報が必要です。

score 2 · Accepted Answer

実際、最も重要なことは、使用する用語が簡単に検索できるようにすることだと思います。重複するバグのほとんどは、標準外の用語の使用に起因します。

正確なフォーマットに関しては、それほど重要ではないと思います。あらゆる形式で恐ろしいチケットを作成することは可能です。

適切な人に誘導するのに役立つ基本的なメタデータ (コンポーネント、プラットフォーム、および重要性) が存在する限り、他のすべてはおまけであり、テキストの説明だけで十分です。

ほとんどのプログラマーは、何が関連している可能性があるかを十分に理解できると思います。Web アプリケーションに問題がある場合はブラウザーのバージョンを報告しますが、使用しているプロセッサの数や正確な OS のバージョンについては言及しません。蒸留できるかどうかなどを再現する手順について説明します。

score 1 · Accepted Answer

私がこれまでに見た中で最もよく書かれた意見の 1 つは、Simon Tatham (PuTTY のライター) によるものです: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html。

バグを効果的に報告する方法

Simon Tatham 著、プロのフリーソフトウェアプログラマー

序章

公共の使用のためにソフトウェアを作成したことがある人なら、おそらく少なくとも 1 つの悪いバグレポートを受け取っているでしょう。何も言わないレポート (「うまくいかない!」); 意味のないレポート; 十分な情報を提供しないレポート。間違った情報を提供するレポート。ユーザーエラーであることが判明した問題の報告。他人のプログラムのせいであることが判明した問題の報告。ネットワーク障害であることが判明した問題のレポート。

技術サポートが恐ろしい仕事と見なされるのには理由があり、その理由は悪いバグ報告です。しかし、すべてのバグ報告が不愉快というわけではありません。私は生計を立てていないときでもフリーソフトウェアを維持しており、時には素晴らしく明快で有益な有益なバグ報告を受け取ることがあります。

このエッセイでは、良いバグレポートとは何かを明確に述べようと思います。理想的には、バグを誰かに報告する前に、世界中のすべての人にこのエッセイを読んでもらいたいと思います。私にバグを報告してくれる人には必ず読んでもらいたいと思います。

簡単に言えば、バグレポートの目的は、プログラマーが目の前でプログラムの失敗を確認できるようにすることです。それらを直接見せるか、失敗させる方法について注意深く詳細な指示を与えることができます. 失敗させることができれば、原因がわかるまで追加情報を収集しようとします。彼らがそれを失敗させることができない場合、彼らはあなたにその情報を収集するように頼まなければなりません.

バグレポートでは、実際の事実 (「私はコンピューターの前にいて、これが起こった」) と推測 (「問題はこれにあると思う」) を明確にするようにしてください。推測は省略しますが、事実は省略しないでください。

バグを報告するのは、バグを修正したいからです。プログラマーをののしったり、故意に役に立たないことを言っても意味がありません: それは彼らのせいであり、あなたの問題である可能性があり、あなたが彼らに腹を立てるのは正しいかもしれませんが、すべての情報を提供して彼らを助ければ、バグはより早く修正されます。彼らが必要とする。また、プログラムが無料の場合、作成者は親切に提供しているので、無礼な人が多すぎると、親切に感じなくなる可能性があることも忘れないでください。

「うまくいきません。」

プログラマーの基本的な知性を称賛してください。プログラムが実際にまったく機能しない場合、プログラマーはおそらく気づいていたでしょう。彼らは気づいていないので、彼らのために働いているに違いありません。したがって、あなたが彼らとは違うことをしているか、あなたの環境が彼らの環境と異なっているかのどちらかです。彼らは情報を必要としています。この情報を提供することがバグレポートの目的です。ほとんどの場合、情報が多いほど、少ないよりも優れています。

多くのプログラム、特に無料のプログラムは、既知のバグのリストを公開しています。既知のバグのリストを見つけることができる場合は、それを読んで、見つけたばかりのバグが既に知られているかどうかを確認する価値があります。すでにわかっている場合は、おそらく再度報告する価値はありませんが、バグリストの報告よりも多くの情報があると思われる場合は、とにかくプログラマーに連絡することをお勧めします。彼らがまだ持っていない情報を提供できれば、彼らはより簡単にバグを修正できるかもしれません。

このエッセイはガイドラインに満ちています。いずれも絶対的なルールではありません。特定のプログラマーには、バグの報告を好む特定の方法があります。プログラムに独自のバグ報告ガイドラインが付属している場合は、それを読んでください。プログラムに付属のガイドラインがこのエッセイのガイドラインと矛盾する場合は、プログラムに付属のガイドラインに従ってください。

バグを報告するのではなく、プログラムを使用して助けを求めるだけの場合は、質問に対する回答を既に探した場所を記載する必要があります。(「私は第 4 章とセクション 5.2 を見ましたが、これが可能かどうかを教えてくれるものは何も見つかりませんでした。」) これにより、プログラマーは人々がどこに答えを期待するかを知ることができるので、ドキュメントを使いやすくすることができます。 .

"見せて。"

バグを報告する最も良い方法の 1 つは、プログラマーにバグを見せることです。彼らをあなたのコンピュータの前に立たせ、彼らのソフトウェアを立ち上げて、うまくいかないことを実演してみせてください。あなたがマシンを起動したり、ソフトウェアを実行したり、ソフトウェアとやり取りしたり、入力に応じてソフトウェアが何をするかを彼らに見てもらいましょう。

彼らは、ソフトウェアが手の甲のようであることを知っています。彼らは、どの部分を信頼しているかを知っており、どの部分に欠陥がある可能性が高いかを知っています。彼らは、何に注意すればよいかを直感的に知っています。ソフトウェアが明らかに間違ったことを実行するまでに、彼らは手がかりを与える可能性のある微妙な間違いにすでに気付いている可能性があります. 彼らは、テスト実行中にコンピューターが行うすべてのことを観察でき、重要なビットを自分で選択できます。

これでは不十分な場合があります。彼らはもっと情報が必要だと判断し、もう一度同じものを見せてほしいと頼むかもしれません。彼らは、何度でも自分でバグを再現できるように、手順を説明するように依頼する場合があります。手順を数回変更して、問題が 1 つのケースだけで発生するのか、関連する一連のケースで発生するのかを確認します。運が悪ければ、一連の開発ツールを使用して数時間座って、実際に調査を開始する必要がある場合があります。しかし、最も重要なことは、問題が発生したときにプログラマーにコンピューターを見てもらうことです。問題が発生していることを確認できたら、通常はそこから問題を解決して修正を試みることができます。

「自分を見せる方法を教えてください。」

これはインターネットの時代です。これは、世界的なコミュニケーションの時代です。これは、ボタンを押すだけで私のソフトウェアをロシアの誰かに送ることができる時代であり、彼はそれについてのコメントを私に簡単に送ることができます. しかし、彼が私のプログラムに問題を抱えている場合、プログラムが失敗している間、私を前に立たせることはできません。「見せて」は、できるときは良いのですが、できないことがよくあります。

直接会うことができないプログラマーにバグを報告する必要がある場合、この演習の目的は、プログラマーが問題を再現できるようにすることです。プログラマーにプログラムの独自のコピーを実行させ、同じことを実行させ、同じ方法で失敗させてもらいたいとします。問題が目の前で起こっているのを見ることができれば、彼らはそれに対処することができます。

だから、あなたが何をしたかを正確に伝えてください。グラフィカルプログラムの場合は、どのボタンを押したか、どの順序で押したかを伝えます。コマンドを入力して実行するプログラムの場合は、入力したコマンドを正確に示します。可能な限り、入力したコマンドとそれに応じてコンピューターが出力した内容を示す、セッションの逐語的なトランスクリプトを提供する必要があります。

考えられるすべての情報をプログラマーに提供してください。プログラムがファイルから読み取る場合は、おそらくファイルのコピーを送信する必要があります。プログラムがネットワークを介して別のコンピューターと通信する場合、おそらくそのコンピューターのコピーを送信することはできませんが、少なくともそのコンピューターの種類と、(可能であれば) そのコンピューターで実行されているソフトウェアを伝えることはできます。

「うまくいきました。では、何がうまくいかないのですか？」

プログラマーに入力とアクションの長いリストを渡して、プログラマーが独自のプログラムのコピーを起動しても何もうまくいかない場合、十分な情報を提供していません。おそらく、すべてのコンピューターで障害が発生するわけではありません。あなたのシステムと彼らのシステムは、何らかの点で異なる場合があります。おそらく、あなたはプログラムが何をすべきかを誤解しており、2 人ともまったく同じ画面を見ているのに、あなたはそれが間違っていると思っていて、彼らはそれが正しいことを知っています。

また、何が起こったのかを説明します。あなたが見たものを正確に伝えてください。あなたが見たものが間違っていると思う理由を彼らに伝えてください。さらに良いことに、あなたが見たいと思っていたことを正確に伝えてください。「それからうまくいかなかった」と言うなら、あなたはいくつかの非常に重要な情報を忘れています。

エラーメッセージが表示された場合は、プログラマーに注意深く正確に、その内容を伝えてください。彼らは重要です！この段階では、プログラマーは問題を解決しようとはしていません。問題を見つけようとしているだけです。彼らは何がうまくいかなかったのかを知る必要があり、それらのエラーメッセージはそれを知らせるためのコンピュータの最善の努力です. エラーを思い出す簡単な方法が他にない場合は、エラーを書き留めてください。ただし、エラーメッセージが何であったかを報告できない限り、プログラムがエラーを生成したことを報告する価値はありません。

特に、エラーメッセージに数字が含まれている場合は、プログラマーにそれらの数字を教えてください。それらに意味が見えないからといって、意味がないわけではありません。数値には、プログラマーが読み取ることができるあらゆる種類の情報が含まれており、重要な手がかりが含まれている可能性があります。エラーメッセージに数字が表示されているのは、コンピュータが混乱してエラーを言葉で報告できないためですが、重要な情報を何らかの方法で取得するために最善を尽くしているためです。

この段階で、プログラマーは効果的に調査作業を行っています。彼らは何が起こったのかを知りませんし、自分自身でそれが起こっているのを見るのに十分近づくことができないので、彼らはそれを明らかにする手がかりを探しています. エラーメッセージ、理解できない数字の列、説明のつかない遅延などはすべて、犯罪現場での指紋と同じくらい重要です。持っておく！

Unix を使用している場合、プログラムがコアダンプを生成した可能性があります。コアダンプは手がかりの特に優れたソースであるため、捨てないでください。一方で、ほとんどのプログラマーは巨大なコアファイルを警告なしに電子メールで受け取ることを好みません。また、コアファイルにはプログラムの完全な状態の記録が含まれていることに注意してください。関連する「秘密」(プログラムが個人的なメッセージを処理していたり、機密データを処理していた可能性があります) がコアファイルに含まれている可能性があります。

「それで、やってみました……」

エラーやバグが発生したときに実行できることはたくさんあります。それらの多くは問題を悪化させます。私の学校の友人は、間違ってすべての Word 文書を削除してしまい、専門家の助けを求める前に、Word を再インストールしてから、デフラグを実行してみました。これらはどちらも彼女のファイルを復元するのに役立ちませんでした。それらの間で、世界中のどの Undelete プログラムでも何も復元できないほどに、彼女のディスクをスクランブルしました。放っておけばチャンスがあったかもしれない。

このようなユーザーは、隅に追いやられているマングースのようなものです。壁に背を向け、特定の死が目の前にあるのを見て、必死に攻撃します。何かをすることは何もしないよりはましでなければならないからです。これは、コンピューターが生成する問題の種類にはあまり適していません。

マングースになる代わりにカモシカになりましょう。カモシカは、予期しないものや恐ろしいものに直面すると、凍りつきます。それは完全にじっとしていて、注意を引かないように努めますが、立ち止まって考え、最善のことを実行します。(カモシカにテクニカルサポートラインがあれば、この時点で電話をかけることになります。) 次に、最も安全な方法を決定すると、それを行います。

何かがうまくいかないときは、すぐに何もしないでください。ボタンには一切触れないでください。画面を見て、いつもと違うことに気づき、それを覚えるか、書き留めます。次に、「OK」または「キャンセル」のうち、最も安全と思われる方を慎重に押し始めます。反射反応を起こしてみてください。コンピューターが予期しないことをした場合は、フリーズします。

影響を受けたプログラムを終了するか、コンピューターを再起動することによって、問題から抜け出すことができた場合は、もう一度問題を解決することをお勧めします。プログラマーは、何度も再現できる問題を好みます。幸せなプログラマーは、バグをより迅速かつ効率的に修正します。

「タキオン変調は間違って分極されているに違いないと思います。」

悪いバグレポートを作成するのは、プログラマー以外の人だけではありません。私が今まで見た中で最悪のバグレポートのいくつかは、プログラマーからのものであり、優れたプログラマーからのものですらあります。

私はかつて別のプログラマーと仕事をしたことがあり、彼は自分のコードでバグを見つけて修正しようとしていました。彼は時々、自分では解決できないバグにぶつかり、私に助けを求めてきました。「どうしたの？」私は尋ねます。彼は、何を修正する必要があるかについての現在の意見を教えてくれました。

彼の現在の意見が正しかった場合、これはうまくいきました。それは彼がすでに仕事の半分を終えたことを意味し、私たちは一緒に仕事を終えることができました. 効率的で便利でした。

しかし、多くの場合、彼は間違っていました。プログラムの特定の部分が誤ったデータを生成している理由を突き止めようと、しばらく作業を行いましたが、最終的にはそうではないことがわかり、完全に適切なコードを 30 分間調査していたことがわかりました。そして、実際の問題は別の場所にあるということです。

私は彼が医者にそれをしないと確信しています。「ドクター、ハイドロヨーヨーダインの処方箋が必要です。」人々は医者にそれを言ってはいけないことを知っています. そうでなければ、医師はあなたを心気症またはクラックポットとして却下します。

プログラマーも同じです。独自の診断を提供することが役立つ場合もありますが、常に症状を述べてください。診断はオプションの追加であり、症状を与えることに代わるものではありません。同様に、問題を修正するためにコードに変更を送信することは、バグレポートに追加するのに便利ですが、バグレポートの適切な代替にはなりません。

プログラマーが追加情報を求めてきたら、でっち上げないでください! 誰かが私にバグを報告してくれたことがあります。私が彼に試してみるように頼んだのは、2 つの異なるエラーメッセージのどちらが表示されるかを知りたかったからです。どのエラーメッセージが返されたかがわかれば、重要な手がかりが得られます。しかし、彼は実際にそれを試したわけではなく、「いいえ、それはうまくいきません」と私にメールで返信しただけでした。彼に実際に試してみるよう説得するのに少し時間がかかりました。

あなたの知性を使ってプログラマーを助けることは問題ありません。あなたの推測が間違っていたとしても、プログラマーはあなたが少なくとも彼らの生活を楽にしてくれたことに感謝すべきです。しかし、症状も報告してください。

「それはおかしい、ちょっと前にやった」

プログラマーに「断続的な障害」と言って、彼らの顔が落ちるのを見てください。簡単な問題とは、単純な一連のアクションを実行すると障害が発生する問題です。プログラマーは、綿密に観察されたテスト条件下でこれらのアクションを繰り返し、何が起こるかを非常に詳細に監視できます。あまりにも多くの問題がそのようには機能しません: 週に 1 回失敗するプログラム、ブルームーンに 1 回失敗するプログラム、またはプログラマーの前で試しても決して失敗しないプログラムがありますが、締め切りが近づくと常に失敗します。上。

ほとんどの断続的な障害は、真に断続的なものではありません。それらのほとんどは、どこかに何らかのロジックを持っています。マシンのメモリが不足しているときに発生するものもあれば、別のプログラムが不適切なタイミングで重要なファイルを変更しようとしたときに発生するものもあれば、1 時間の前半だけに発生するものもあります。（実際に見たことがあります。）

また、バグを再現できるのにプログラマーが再現できない場合は、プログラマーのコンピューターとあなたのコンピューターが何らかの形で異なり、この違いが問題を引き起こしている可能性があります。かつて、画面の左上隅でウィンドウが丸まって小さなボールになり、そこに座って不機嫌になったプログラムがありました。しかし、それは 800x600 の画面でしかできませんでした。私の1024x768モニターでは問題ありませんでした。

プログラマーは、問題についてあなたが見つけられることは何でも知りたいと思うでしょう。おそらく、別のマシンで試してみてください。2 回または 3 回試して、失敗する頻度を確認します。本格的な作業を行っているときに問題が発生し、デモンストレーションを行っているときに問題が発生しない場合は、実行時間が長いか、大きなファイルが原因で失敗する可能性があります。倒れたときに何をしていたのか、できる限り詳しく覚えておいてください。パターンが見られた場合は、それについて言及してください。あなたが提供できるものはすべて、何らかの助けになるはずです。確率的なものにすぎない場合でも (「Emacs を実行しているときに頻繁にクラッシュする傾向がある」など)、問題の原因の直接的な手がかりにはならないかもしれませんが、プログラマーが問題を再現するのに役立つ可能性があります。

最も重要なことは、プログラマーは、実際に断続的な障害を処理しているのか、それともマシン固有の障害を処理しているのかを確認したいということです。彼らはあなたのコンピューターについて多くの詳細を知りたいと思うでしょう。これらの詳細の多くは特定のプログラムに依存しますが、提供する準備が整っている必要があるのは、バージョン番号です。プログラム自体のバージョン番号、オペレーティングシステムのバージョン番号、およびおそらく問題に関与している他のプログラムのバージョン番号。「それで、ディスクを Windows にロードしました . . .」

バグレポートでは、明確に書くことが不可欠です。プログラマーがあなたの意図を理解できない場合、あなたは何も言わなかったはずです。

世界中からバグレポートを受け取ります。彼らの多くは英語を母国語としない人であり、彼らの多くは英語が下手であることを謝っています. 一般に、貧弱な英語に対する謝罪を含むバグレポートは、実際には非常に明確で有用です。最も不明確なレポートはすべて、英語を母国語とする人からのものであり、たとえ彼らが明確または正確であろうと努力しなくても、私がそれらを理解すると思い込んでいます.

具体的に。同じことを 2 つの異なる方法で行うことができる場合は、どちらを使用したかを述べてください。「ロードを選択しました」は、「ロードをクリックした」または「Alt-L を押した」という意味かもしれません。あなたがしたことを言ってください。時にはそれが重要です。
冗長にします。少ないよりも多くの情報を提供してください。あなたが言いすぎると、プログラマーはその一部を無視することができます。あなたの発言が少なすぎると、彼らは戻ってきて、さらに質問をしなければなりません。私が受け取ったバグレポートは 1 文でした。私がさらに情報を求めるたびに、記者は別の一言で答えました。一度に 1 つの短い文が表示されるため、有用な量の情報を取得するのに数週間かかりました。
代名詞に注意してください。「それ」のような言葉や「窓」のような参照は、意味が不明確な場合は使用しないでください。「FooApp を起動しました。警告ウィンドウが表示されました。閉じようとしたところ、クラッシュしました。」ユーザーが何を閉じようとしたかは不明です。彼らは警告ウィンドウを閉じようとしましたか、それとも FooApp 全体を閉じようとしましたか? それは違いを生みます。代わりに、「警告ウィンドウを表示する FooApp を開始しました。警告ウィンドウを閉じようとしましたが、FooApp がクラッシュしました」と言うことができます。これはより長く、より反復的ですが、より明確で誤解しにくいものでもあります。
あなたが書いたものを読んでください。レポートを自分自身に読み返し、それが明確であると思うかどうかを確認してください。失敗を引き起こす一連のアクションをリストした場合は、それらを自分でたどって、ステップを見逃していないかどうかを確認してください。

概要

バグレポートの第一の目的は、プログラマーが自分の目で失敗を確認できるようにすることです。目の前で一緒に失敗させることができない場合は、彼らが自分で失敗できるように、詳細な指示を与えてください。
最初の目的が成功せず、プログラマー自身が失敗していることに気付かない場合、バグレポートの 2 つ目の目的は、何がうまくいかなかったかを説明することです。すべてを詳細に説明してください。あなたが見たものと、あなたが見たいと思っていたものを述べてください。特に番号が含まれている場合は、エラーメッセージを書き留めます。
コンピュータが予期せぬことをすると、フリーズします。落ち着くまでは何もせず、危険だと思うこともしないでください。
できると思われる場合は、必ず自分で障害を診断してみてください。ただし、診断した場合でも、症状を報告する必要があります。
プログラマーが必要とする場合は、追加情報を提供できるようにしておいてください。彼らがそれを必要としないなら、彼らはそれを求めていないでしょう. 彼らは故意にぎこちなくしているわけではありません。バージョン番号はおそらく必要になるため、手元に置いておいてください。
はっきりと書く。言いたいことを言い、誤解されないようにします。
何よりも、正確であること。プログラマーは精度が好きです。

免責事項: 私はマングースやカモシカを実際に見たことはありません。私の動物学は不正確かもしれません。

$Id: bugs.html 8168 2008-09-08 18:03:28Z simon $

score 0 · Accepted Answer

同様に重要なのは、WHO が「再現手順」などの問題フィールドを実際に確認して入力できることを理解することです。間違った人に尋ねると、彼らはあなたにゴミデータを与えるでしょう.

ここで役立つアドバイス