Quality Centralでのバグレポートのコツ

投稿者:: Yusuke Konno

概要: Quality Centralでのバグレポートの際のコツを紹介します。

Embarcaderoの製品を使っていて、バグレポートや新機能提案を行いたい時にはQuality Centralを使用します。しかし、Quality Centralでは英語でレポートしなければならないため、英語を母国語としない日本人にとっては敷居が高いようにも思えます。また、折角時間を割いてレポートをしたにもかかわらず、レポートが理解されないという事も少なからずあるようです。

ところが、レポートが理解されない原因のほとんどが、Quality Centralのレポートの作法を分かっていない」ことに気づいている人は少ないようです。英語があまり得意でない人でも、コツさえつかんでしまえば簡単に通じるレポートが書けるようになります。今回はバグレポートと新機能リクエストの”書き方のコツ”を紹介します。

    レポートがうまくいかない原因

    英語力は関係ない

もし、あなたがQuality Centralにレポートを投稿した経験があって、バグレポートが上手く伝わらず、その原因がご自身の英語力にあると考えているのであれば、おそらくそれは大きな間違いです。

QCにレポートを投稿する上で、必要な英語力(特に文法)は中学校を卒業できるレベルであれば十分です。語彙・表現は辞書を使えばいくらでも補えますから、全く問題になりません。また、Embarcaderoのスタッフも全員が英語を母国語としているわけではありませんから、難解な言い回しができたところで通じない可能性は十分にあります。

レポートが上手く行かない原因は、何を書かなければならないかを知らないからです。逆に言えば、それさえ知っていれば英語力が無くても何とかなってしまうと言うことです。

    バグレポートの本質

バグレポートは以下の機能を果たせばOKです。

  • 担当者に不具合(と思われる事象)を再現させることが出来る
  • 投稿者にとっての、あるべき挙動と実際の挙動が明記されている
  • 担当者に当該不具合がどのような影響を与えているのかを理解させることが出来る

以上から、QCにバグレポートを登録する際には、Steps to Reproduceが最も重要なファクターであることが分かります。

    作業の手順は日本語→英語

もし英語が苦手であるのならば、まず適当なテキストエディタに日本語で下書きをしましょう。日本語で完璧なレポートを作成できれば、あとはそれを単に翻訳すればよいだけです。つまり翻訳という作業を機械的なものに出来ます。無理に英語でレポートを起草しようとすると、英語にばかり集中してしまうことになり、大抵は抑えるべきポイントが抑えられていないレポートが出来上がる結果になります。

    Windowsクライアントを使ったバグレポートの投稿

    0.投稿の前に:QCでの決まり事

QCには暗黙の"お決まり"があります。レポートの際にはこのお決まりを守りましょう。

    投稿は全て英語

投稿は全て英語で行います。日本語で行ってはいけません。理由は、根本的にQC自体が日本語に対応していないというのもありますが、基本的にEmbarcaderoの開発スタッフ全員が理解できる言語は英語のみだからです。

ただし、UIや文字列関係のレポートで、日本語をどうしても扱わなければならない時があります。その際はコントロール文字列に置き換える、画像を添付する等の工夫が必要です。

    投稿は自分で

以前はBorlandのニュースグループで代理投稿が行われていましたが、現在は行われていません。現在では代理投稿の依頼を出すこと自体NGですのでご注意下さい。

    1つのレポートにつき、1つの事象を書く

当たり前のことですね。1つのレポートに複数の事象を含めてはいけません。複数のコンポーネントに同じ問題が発生するような場合でも、コンポーネント毎に分けてレポートを行うべきです。

    クレームを書かない

レポートの本文中にクレームを書いてもあまり意味がありません。クレームを書くと段々ヒートアップしていくため余計な事ばかり書くようになり、肝心な書くべき事が抜けたり、不明瞭になったりする恐れがあります。(書きたくなる気持ちは分からなくはないですが)

    添付ファイルはZIP

QCにはファイルを添付することが出来ますが、ZIP形式以外には対応していません。画像1枚の場合でもZIPにしてアップロードする必要があります。

    1. 細かい情報の設定

QCのWindowsクライアントを起動してログインをしたら、まずInsertを実行します。そうすると新しいレポートの投稿が可能になります。まずは記述を始める前に製品やレポートの種類などを設定していきます。

    Locale

日本語版を使っているのであれば、JapaneseでOKです。もし、英語版でも同様の不具合を再現できた場合にはUSにします。また、アジア圏限定の問題などであればAsianないしInternational等に設定します。ただ、ロケールについてはQuality Centralの管理者が適切な値を設定し直すのがほとんどなので、基本的にJapaneseで問題ありませんし、英語版で追加的にテストする必要もありません。

    Area

エリアには、最も妥当と思われるカテゴリを指定します。フィールドテスト時などは新機能について適切なカテゴリが存在しないこともあるので、その場合は親となるカテゴリ(VCLとかCode Editorとか)に設定しましょう。

    2. Short Description

Short Descriptionは実質的にレポートのタイトルです。記述すべき内容は、"レポートの内容を最も端的に表すもの"です。端的にとは、"具体的かつ明確に"という意味です。

ちょっと例を挙げてみましょう。
例えばTEncoding.GetEncodingがメモリリークを起こすという不具合があったとします。これをレポート化するにあたって、Short Descriptionに以下の記述をしたとします。

"TEncoding.GetEncoding has a serious bug."

日本語訳をすると「TEncoding.GetEncodingには深刻なバグがある」になります。分かると思いますが、全然具体的でも明確でもありません。

この記述のダメなところは、

・バグの内容が明確に表現できていない

という点です。
そもそもバグレポートかどうかはReport Typeで分かりますし、深刻なバグかどうかはSeverityで分かります。

これについて、あるべき記述は以下のようになります。

"TEncoding.GetEncoding causes memory leak."

日本語訳をすると「TEncoding.GetEncodingがメモリリークを起こす」になります。不具合の内容をズバリ指摘できています。今回の設例はあまりにも単純な内容でしたが、実際には不明瞭な記述のレポートが散見されます。気をつけましょう。

Short Descriptionを短く抑えるには--
バグによっては、特定の条件を満たさないと発生しないと言ったようなものもあります。この場合、条件についていちいちShort Descriptionに記述してしまうと、かなり長いタイトルになってしまいます。こう言った場合には、発生条件などはある程度ぼやかしてしまってOKです。大事なのは、バグの内容が何なのかが端的に表現されていることです。条件など、付属的なものはDescriptionの方に記載するようにしましょう。

    3. Description

Descriptionは複数行のエディットなので、長い記述をすることが出来ます。バグレポートの時は以下のこと具体的に書けばよいでしょう。

  • バグの内容
  • バグの発生条件
  • バグの発生原因(特定できている場合)
  • バグが発生するとどのようなことで困るのか
  • バグの回避策(存在する場合:修正方法ではない!
  • 添付ファイルの内容

ここで大事なことは、バグの再現方法はDescriptionに書かないということです。再現手順はかならずSteps to Reproduceに記述します。また、サンプルコードなどもSteps to Reproduceに記述します。

Hide image
Click to see full-sized image

上記の例ではバグの概要と発生条件および発生原因、バグが発生するとどのようなことで困るのかについての記載がなされています。

    4. Steps to Reproduce

QCにおけるバグレポートで、最重要項目です。バグの再現手順を記述します。ここの書き方を失敗すると、高確率でNeed More Info行きです。

再現手順は、箇条書きで順番に丁寧に記述することを強く推奨します。箇条書きにすることで、冗長な表現を避けることができ、レポートの可読性が上昇します。また、手順に何らかの不備があった際にもその指摘や修正が非常に容易です。

手順を箇条書きで書いたら、最後に必ず書かなければならないことがあります。それは予想した挙動と実際の挙動です。通常、予想した挙動は"EXP"という見出しを付けて、実際の挙動は"ACT"という見出しを付けて記述します。

これらを書く理由は、仮に再現手順がちゃんと記述されていて、担当者が再現に成功したとしても、担当者が再現した事象を不具合と認識するという保証がないためです。動作が仕様であった場合や担当者が不具合を理解していない場合、そう言った状況になります。そのため、最後にEXPとACTの記述は必ず必要になるのです。ここをおろそかにするとやはり高確率でNeed More Info行きです。

Hide image
Click to see full-sized image

上記例では、バグの再現手順を箇条書きで記述しています。また、再現のために必要なコードも記載しています。そして、最後には予想した挙動をEXPの見出しを付けて、実際の挙動をACTの見出しを付けて記載しています。

    5. Attachment

再現手段を書いたら、添付ファイルを用意しましょう。添付ファイルは必ずしも必要なわけではありませんが、

用意しておくと担当者の理解を促進するのに大きく寄与します。添付すべきファイルは、大別するとバグのスクリーンショットまたはバグを再現できるプロジェクト一式です。

    スクリーンショット

バグのスクリーンショットを添付します。あらゆる局面で効果的です。なぜなら担当者が視覚的に不具合の内容を認識することが可能だからです。とりわけ、日本語にまつわる不具合(UI、文字処理等)は、担当者の環境で常に再現できるわけではありません。非常に重要です。

Hide image
codetemplate

    プロジェクト

可能であれば、不具合を再現できる最小のプロジェクトを用意し、それを添付すると効果的です。この際、ファイルのエンコーディングは必要に応じて適切に設定にしておきましょう。ANSIだと日本語の文字列等が担当者の環境如何では欠落する恐れがあるからです。

    6. Workaround

もし、あなたが不具合の解決策を知っているのであれば、Workaroundに書いてみましょう。Workaroundの内容は、書いても承認されないと採用にならないので、必ずしも採用されるわけではありませんが、バグの早期解決には貢献するでしょう。

    新機能リクエストのコツ

    バグレポートとの違い

    具体性が欠けやすい機能要求

バグレポートと違い、機能要求は内容の具体性が欠け、不明瞭になりがちです。なぜなら、個別的な機能であれば具体的な要求がしやすいですが、大局的な機能要求をした時にはどうしても抽象的になってしまうからです。

例えば、64ビットに対応して欲しいという要求があったとします。この要求はかなり大局的・抽象的です。なぜなら、どの機能をどう改良して64ビット化を実現するという事が全く示されていないからです。しかし多くの場合、機能要求で実現のために必要な手順を全て示すことはほぼ不可能です。

一応レポートとして上記要求は受理されます。が、機能要求時にはこの点をよく把握しておく必要があります。

    提示しなければならない内容

機能要求をレポートにする際には以下のことを示す必要があります。

  • 実装して欲しい機能の内容(どのようなことが実現できれば良いのかをできるだけ具体的に)
  • なぜその機能が必要なのか
  • どのような不具合があるのか(その機能がないとどういった点で困るのか)

    背理法:論述の武器

背理法とは大雑把な言い方をすれば、「もし○○でなかったら××となり矛盾する。よって○○である。」という証明方法です。これを機能の必要性の論述に応用すれば、「もし○○が存在しないと××になって困る。よって○○は必要である。」と論述すればOKです。

実際にレポートにする際には、論文のように記述する必要はありませんが、流れが背理法的になるように記述すると良いと思われます。

    最も重要なもの

完璧なレポートが出来たとしても、要求が採用されるとは限りません。要求の採用可能性を上げるためには、Voteを募るのが最良の手段です。なぜなら、Voteの数は重要だと思っているユーザーの数であり、重要性の判断基準になっているからです。

どうしても実現して欲しい機能なら、できるだけフォーラムなどでVoteを募りましょう。

    作業の手順は日本語→英語

機能要求レポートはバグレポートよりも大変です。バグレポートでも書きましたが、 もし英語が苦手であるのならば、まず適当なテキストエディタに日本語で下書きをしましょう。

    Windowsクライアントを使った新機能リクエストの投稿

    1. 細かい情報の設定

QCのWindowsクライアントを起動してログインをしたら、まずInsertを実行します。そうすると新しいレポートの投稿が可能になります。まず、記述を始める前に製品やレポートの種類などを設定していきます。

Locale

特に考える必要はありません。Japaneseで良いでしょう。

Area

エリアには、最も妥当と思われるカテゴリを指定します。全くの新しい機能であれば、最も妥当な大枠となるカテゴリを選択すると良いでしょう。

Report Type

全くの新機能であれば、New Feature Requestを、既存機能の強化案であれば、Suggestion / Enhancement Requestを選択します。

Severity

通常はCommonly encountered problemでしょう。他の項目だとあまり説得力がない気がします。

    2. Short Description

Short Descriptionは実質的にレポートのタイトルです。記述すべき内容はバグレポート同様、"レポートの内容を最も端的に表すもの"です。端的にとは、"具体的かつ明確に"という意味です。

Short Descriptionの先頭に[Request]等の記述をしておくと、レポートが機能要求であることが見出しレベルで分かるので便利です。

    3. Description

Descriptionは複数行のエディットなので、長い記述をすることが出来ます。機能要求レポートの時は以下のこと具体的に書けばよいでしょう。

  • 実装して欲しい機能の内容(どのようなことが実現できれば良いのかをできるだけ具体的に)
  • なぜその機能が必要なのか
  • どのような不具合があるのか(その機能がないとどういった点で困るのか)

必要性などは列挙事項であるのならば箇条書きで書くとよいです。できるだけ理由は多く書いた方がアピールとしては強いと思って差し支えありません。

Hide image
Click to see full-sized image

上記の例では、新機能の概要と必要性、新機能がないことによってどのような事で困るのかについて列挙されています。列挙自由は基本的に箇条書きで書いた方が楽な上に見やすいです。

    4. Steps to Reproduce

機能要求では、特に書かなくても問題ありません。ただし、既存の機能で問題が発生する際には、その問題の再現手順やサンプルコードなどを記述すると効果的です。

    5. Attachment

通常、添付すべきものがないことがほとんどです。

    6. Workaround

もし、あなたが実装方法を知っているのであれば、Workaroundに書いてみましょう。Workaroundの内容は、書いても承認されないと採用にならないので、必ずしも採用されるわけではありませんが、機能の早期実現に貢献するでしょう。

    レポートを終えたら

    レポートは、投稿しただけでは効果がない!

QCのレポートを提出しても、受理されなければ何にもなりません。提出したまま放置していると、そのまま気づかれないこともありうるので、フォーラムに投稿することで投稿した旨を担当者に知らせるべきです。投稿するフォーラムは日本語フォーラムだけでなく、該当の製品の適切なグループに投稿しましょう。そうすることで担当者が直接レポートを閲覧できますし、他のユーザーの関心を引きつけることも可能です。

    Voteの重要性

Voteはレポートに対して投票を行う非常に重要なアクションです。なぜなら、投票数が多いレポートほど、重要性が高いと判断されやすくなるからです。重要性が上がると、不具合が早期に修正されたり、新機能として採用されやすくなったりします。実際に、不具合自体の重要性はあまり高くないレポートが、Voteを多く集めたことによって重要性が上がり、早期に修正された例もあります。

自分や周囲のユーザーにとって深刻な問題であっても、すぐに修正がされる保証はありません。どうしてもすぐに修正して欲しい場合にはVoteを募ることがとても重要です。また、新機能リクエストの際にはVoteの数がかなり重要です。数百のVoteが集まっているレポートは、おいそれと無視できないものとして取り扱われているはずです。

    レポートに動きがあったら

レポートがClosedになっても、問題はまだ解決していないことがあります。

    Closedされた理由が不服な時

ResolutionがAs Designedとなったとしても、仕様としてしまうことが妥当とは限りません。もし、As Designedとなったことが不服なのであれば、レポートの内容をより充実させ、不服である旨と理由をQCのコメントに記入するか、フォーラムに投稿しましょう。場合によっては覆せる可能性もあります。

    ReportedまたはPendingのまま更新されない

投稿をしたのにReportedのままだったり、レポートの内容を修正したのにもかかわらずPendingで放置されたりしている時は、担当者に申告するか、フォーラムに投稿しましょう。放置されている理由の説明を求めるのも良いかも知れません。

とにかく、ダメだと思って引き下がってしまわないことが重要です。納得がいくまでプッシュを続けることがとても大事です。遠慮は要りません、ガンガンプッシュしていきましょう。

次からのサーバー応答:: ETNASC04