バグ記入ガイドライン

なぜあなたがこの文章を読まなくてはいけないのか？

簡単に言うと、より効果的にバグ報告ができるようになれば、エンジニアがバグを修正する可能性も高くなるからです。

このバグ記入ガイドラインは、バグ報告を書くのに慣れていない人たちへの一般的なチュートリアルです。全ての部分があなたのソフトウェアプロジェクトに適用できるとは限りません。

役に立つバグレポートの書き方

役に立つバグレポートとは、バグを修正させてしまうレポートです。役に立つバグレポートは通常二つの特性を持ちます:

  1. 再現可能。 もしエンジニアがそのバグを確認できない、またはそれが存在することを確実に証明できないならば、そのエンジニアはそのバグを "WORKSFORME" または "INVALID" に印を付け、次のバグへとりかかるでしょう。あなたの提供できるどんな説明も、助けとなります。

  2. バグの原因を特定しやすい。 エンジニアがそのバグを特定の問題へと切り分けられるのが早いほど、より良く修正される可能性が高まるでしょう。(もしプログラマーやテスターがバグを解読しなくてはならない場合、修正とテストより、報告者への文句を考えるほうに多くの時間を費やします)

    [ もっと聞きたい ]

あなたのテストしているアプリケーションは WWWブラウザだと伝えましょう。foo.com でクラッシュして、バグレポートを書こうと思ったら:

よくない例:「わたしのブラウザがクラッシュしました。たしか foo.com に行ったときです。 ビルゲイツ OS を使ってますから、すぐ直したほうがいいですよ、でないと彼に報告しちゃいますよ(ｗ。 ところで、アイコンのデザインがつぶれたネズミみたいなんすけど。このデザインはだめっすね。 あと、わたしの祖母のホームページもこのブラウザだとうまく見られないですよ。それではヨロシク」

よい例:「foo.com に行くといつもクラッシュします。僕の使っているのは 2002-02-25 で、Windows 2000 です。Linux でやってみても再現します。Linux 版は 2002-02-24 版です。

あと、ページのトップに Foo のバナーを表示しようとするといつも落ちます。ページを解析してみたら、次の画像へのリンクがあるといつもクラッシュします。"border=0" を削除するとクラッシュしません:

<IMG SRC="http://www.foo.com/images/topics/topicfoos.gif" width="34" height="44" border="0" alt="News"> 」

役に立つバグレポートの Bugzilla への登録の方法:

バグを入力する前に、あなたの見つけたバグはすでに報告されているかどうかを Bugzilla の検索ページで調べてください (もしあなたのバグがすでに知られた問題の 37個目の重複だったら、担当者をいらいらさせてしまうでしょう。いらいらしたエンジニアは解決できるバグが少なくなります)。

次に、バグが最新版でも発生するかを確認してください。エンジニアは、今取り組んでいるコード上で発生する問題に関心を持つ傾向があります。バグ自体が既に修正されているかもしれません。

もし最新版で発生する新規バグを発見したら、Bugzilla で報告してください:

  1. Bugzilla のメインページから、「新規バグ登録」を選んでください。
  2. バグを発見したプロダクトを選択します。
  3. メールアドレスとパスワードを入力して、"Login"ボタンを押します。 (もしまだパスワードを持ってないのでしたら、パスワードの入力部分を空にして、"E-mail me a password" ボタンを押してください。パスワードの含まれたメールが送られてきます。)

では、フォームを入力します。それぞれの意味は次のようになります:

どこでバグを発見したか?

プロダクト: どのプロダクトで、このバグを見つけたのか？
さきほどのページで選んだばかりです。

バージョン: どのバージョンのプロダクトで、このバグを見つけた？
もし適切なものがあれば。

コンポーネント: どのコンポーネントにバグがある？
バグレポート記入のさいには、コンポーネントを選ぶことが必要になります。意味がわからないときは、「コンポーネント」のリンクをたどり説明を読んで、いちばんいいと思うものを選んでおいてください。

OS: どの オペレーティングシステム (OS) でバグを見つけました？ (例 Linux, Windows 2000, Mac OS 9)
どのOSでも起きるなら、'All'を選びましょう。そうでなければ、そのOSか、'Other'を選びます。

そのバグはどれくらい重要か？

重要度 (Severity): そのバグの与えるダメージの大きさ
デフォルトは「 normal 」です。(もっとも適切な重要度を選ぶには、「重要度」リンクをクリックして説明を読んでください)。

誰がこのバグに従事するのか？

担当者 (Assigned To): どのエンジニアがこのバグの修正に責任を持つのがいいか
Bugzillaは、バグが投稿されたとき、バグレポートを自動的にデフォルトのエンジニアに割り当てます。このテキストボックスは、別のエンジニアを指定するときに使います。(各コンポーネントごとに決まっているデフォルトのエンジニアを見たいときは、「コンポーネント」リンクをクリックします)。

Cc: このバグレポートに加えられた変更をメールで受け取る人
このバグレポートに変更が加えられたとき、当事者(報告者、担当者)以外でメールを受け取る人。複数のメールアドレスを指定することができます。そのときは、スペースかコンマで分けて記入します。

エンジニアに伝えることができる そのほかのこと

要約 (Summary): 半角 60 文字程度で、このバグをどう表現するか。
良い要約とは、すぐ分かり、ほかのバグレポートと区別がしやすいものです。 そうでないと、エンジニアが要約を見ただけでは意味がつかめず、そのバグレポートに注意を払わなくなりがちです。10 ページにも及ぶバグリストにざっと目を通しているときには。
よい要約とは「東芝 Dynabook780DVD で PC カードインストール失敗」のようになります。「ソフトが動きません」「インストールの問題」はわるい要約です。
[ もっと聞きたい ]

コメント (Description):
この欄に、問題について究明できたものを詳しく記入してください。 バグを受けとる人は、以下のような情報が書かれているのを期待しています:

概略:要約をより詳しく拡大させて書きます。

NSGetFactoryのMacビルドで、ドラッグ選択がどのページでも失敗する。

再現手順: バグを引き起こす最小の手順。準備の段階に特別なことがあればそれも含みます。 

1) ウェブページをどこでもいいので開く。
(私はデフォルトのサンプルページを使用しました。
resource:/res/samples/test0.html)
                          
2) ドラッグ選択する。(特に、マウスボタンを押したまま、
ポインタをブラウザの内容領域の中から領域の下部に移動させたとき)

実際の結果: 上の手順を実行したあと、アプリケーションはどうなるのか Actual Results: What the application did after performing the above steps. 

アプリケーションはクラッシュする。
Stack crawl appended below from MacsBug.

期待される結果: バグがなければ、アプリケーションが本来どう動作すべきか

ウィンドウが下方向にスクロールし、スクロールした中身は
選択されているべき。
(少なくとも、このアプリがクラッシュしてはならない)

日付(バージョン)とプラットフォーム: そのバグを見つけたビルドのプラットフォームと日付

ビルド 2002-03-15, Mac OS 9.0
NetscapeCommunicator 4.5 (MacOS)

追加ビルド・プラットフォーム: ほかのビルド、プラットフォーム(や、ブラウザ) でも起きるかどうか (もし分かればでよい)

- いつも再現する
    Mozilla (2002-03-15 ビルド、Windows NT 4.0) 
- 再現しない
    Mozilla (2002-03-15 Red Hat Linux; 機能がサポートされていないもの)        
    Internet Explorer 5.0 (Windows NT 4.0 に入っているもの)
    Netscape Communicator 4.5 (Mac OS 9.0 に入っているもの)

追加情報: そのほかのデバッグ情報

  • Win32: もし Dr.ワトソンのエラーを受け取ったら、そのクラッシュのタイプとクラッシュしたモジュールを書き取ってください。(例 apprunner.exeのアクセス違反)
  • Mac OS: もしMacsBugを起動していたら、how と sc の結果を提供してください。:
*** MACSBUG STACK CRAWL OF CRASH (Mac OS)
Calling chain using A6/R1 links 
    Back chain  ISA  Caller 
    00000000    PPC  0BA85E74   
    03AEFD80    PPC  0B742248   
    03AEFD30    PPC  0B50FDDC  NSGetFactory+027FC
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0

あなたは書き終わりました！

起こりうるまちがいがないかどうか、2度チェックしたあとで、 [Commit] ボタンをクリックすれば、バグレポートはBugzillaデータベースに登録されます。

よいバグレポートを書くためのさらなる情報

1. 役にたつレポートの一般的なコツ

明快な構成を使いましょう。すると、バグレポートをざっと見ることがやりやすくなります。 バグレポートを読む人は、特定のセクションをすぐ読めることを必要としていることが多いです。もし設置された Bugzilla が Bugzilla Helper をサポートしていれば、それを使用しましょう。

明晰さを失わせるなら、ジョークの類は避けましょう。 3:00 AM に作業していて、書かれたバグの再現方法をレポートから読み取ることができないときに、バグの要約がおもしろくて笑う人はいません。

レポート一つにつきバグ一つ。 バグ修正、修正確認、優先順序付けを行なうのが全然別の人ということはよくあることです。 もしあなたが両手にかかえるほどのバグを一つのレポートにまとめてしまうと、 そのバグを扱うにふさわしい人は、あなたのバグをちょうどよいときに 探し出すことができないかもしれません。 特定のバグは他のバグより重要であるものです。4つの別々の、それぞれ重要度の異なる問題を含んだバグレポートは、優先順序付けができません。

報告する必要もないほど軽微なバグは存在しません。 ソースコードを読んでいるのでないなら、ソフトウェアのバグの真の姿を見たとはいえません。あなたに見えるものはそのバグが実体化したもの、人につきまとうポインター犬のようなものです。たとえばアプリケーションがクラッシュしたときの保護違反など。 深刻なソフトウェアの問題は、外見上はつまらなく見えることがあります。 どんな軽微なバグでも記録し、保存しておきましょう。

2. よいバグの要約を書くための方法とそうしなくてはならない理由

バグレポートを受け取る人によい第一印象を与えたい。 New York Times のヘッドラインが、何十もの選択肢の中から、関連する記事を読者に導くように、あなたのバグの要約も、数百の選択肢の中からあなたのバグレポートは読む価値があると伝わりますか?

逆に言えば、「インストールの問題」 のような曖昧なバグの要約だと、 インストール関連のバグを読む人は それが本当に問題なのかどうかを決めるためだけに、要約を読むだけでなくあなたのバグレポートを全部読まなくてはならないという無駄をしなくてはならなくなります。

バグはその要約だけで検索されることがよくあります。 あなた以外の人はあなたのバグを、webページを探すとき Google で思いついたキーワードによって検索するようなやり方で探すことがあります。具体的なバグの要約は自然にキーワードを多く含み、より簡単に探せます。

たとえば、「リストビューから gnome-terminal にアイコンをドラッグしてもパスが貼り付けできない (Dragging icons from List View to gnome-terminal doesn't paste path)」というタイトルのバグは、"List" か "terminal"、"path"を検索するば見つかります。これらの検索キーワードは「アイコンをドラッグしても貼り付けできない (Dragging icons doesn't paste)」というタイトルのバグでは見つかりません。

自問してみてください。「僕のバグを、要約を見ただけで理解できる人がいるだろうか?」 もしそうであれば、それはよい要約です。

こんな要約は書かないようにしよう:

  1. 「インストールできない」 - インストールできない理由は? インストールしようとしたとき何が起こりました?
  2. 「深刻な動作速度の問題」 - ...それで何をしたときにそれが起きましたか?
  3. 「Back ボタンがききません」 - 最初からずっとですか? 何かして、その結果としてですか?

よいバグの要約:

  1. 「Mozilla M18パッケージがあると 1.0 アップグレードインストールに失敗」 - 問題と状況を説明しよう。
  2. 「Red Hat 6.2 (RPM 3)で RPM 4インストーラを立ち上げるとクラッシュ」 - 何が起きるのかとそのときの状況(環境)を説明しよう。

(Written and maintained by Eli Goldberg. Claudius Gayle, Gervase Markham, Peter Mock, Chris Pratt, Tom Schutter and Chris Yeh also contributed significant changes. Constructive suggestions welcome.)