how to write a on-target (bug) report

「報告 (レポート) しなければ問題は解決されない」は「シュートしないとゴールは生まれない」に近い。

勿論、シュートしなくともゴールが生まれることはある。例えば、オウンゴール。

立場が違うと感じ方に違いはあるかもしれないが、ソフトウェア開発側からすると、報告せずに問題が直るのを期待するのは、オウンゴールを期待しているのに近い。確かにそういこともあるが極めて稀。

しかし、シュートはただ打てば良いというものではなく、少なくとも枠内に飛ばさないと得点には結びつかない。

サッカーとの比較はさておき、実際に問題に遭遇するのは、締切り直前とか、最も忙しい時だったりする。そんな時に悠長にレポートを書く余裕は時間的にも精神的にも無い。

ここでは、「枠内」なレポートを時間をかけずに書く方法を紹介したい。

なお、これは time opcook の記事の代りに、Houdini Apprentice Advent Calendar 2021 の 5日目の記事になりました。

0. 「枠内」なレポートとは

以下の情報の明記が「枠内」と言える。

1. 問題の概要: Houdini のビルド番号 (例: 19.0.460) を含める
2. 問題の再現手順 + 問題が再現可能なシーンファイル
3. 補足情報: マシン情報等

どれかが欠けているのは、枠を外したと言える。逆に、特に上の二つが明瞭であれば、所定の書式というのは不要。

1. 問題の概要

良い「問題の概要」とは、一行なり単一パラグラフで

• 問題 (バグ) か、(機能改善) 要望か、それとも質問か
• ソフトウェアのバージョン及びどの部分、特に Houdini の場合、どのノードか

ということが瞬時に特定できること。

例えば、以下のような概要は分かり易い。

1. 「Volume Wrangle が 19.0 では 18.5 より遅い」
2. 「H19.0.455 で PolyBevel を実行するとクラッシュする」
3. 「UE4.27 と Houdini Engine 19.0.455 で地形に穴を開けようとしているが開かない」
4. 「UE4 Game Starter Kit の HDA が H19.0.455 で動かない」
5. 「H19.0.455 を Mac にインストールしたが起動しない」

ただし、これだけで解決する可能性は極めて低く、もう少し具体的な情報が必要になる。

2. 問題の再現手順

問題の再現手順とはユーザと開発者の間で問題を正しく共有すること。不明瞭な再現方法が満足な結果がつながることはまず無く、再現方法の無いレポートは対応のしようがない。

最も理想的な再現手順とは、最低限の Houdini 知識しか持ち合わせていない人でも再現可能な手順を提示することである。

一つの方法は、再現手順を順番に 1, 2, 3, ... と簡潔に書いていく。例えば #b の場合、

1. Hou1ini 19.0.455 で添付のシーンを開く。
2. /obj/geo1/polyextrude6 を選択。
3. このノードに PolyBevel を接続すると Houdini がクラッシュする。

など。季節の挨拶などは不要。

要シーンファイル

上記 #a や #b のような問題ではシーンファイルが必須。
#c ~ #e では必ずしも要らない。

上記概要を一つずつ見ていくと

1. 「Volume Wrangle が 19.0 では 18.5 より遅い」
   • 問題が簡単に再現できるファイルとその操作手順が必要。
     • 単純かつ小さなシーン構成であればあるほど問題の切り分けが易しくなる。
     • シーンファイルがあれば使われたビルド番号と OS がわかる。
   • 実際には、シーンファイルと手順をもらって検証しても、
     1. H18.5 と H19 の間で Volume Wrangle に変更はなかった
     2. Wrangle が実行していた Worley Noise が疑われる
     3. 担当開発者の環境 (Linux) では速度変わらず
     4. よりピンポイントな計測方法で測ることになった
     5. Windows 版のみ、 ボクセルの配列のマルチスレッド化に問題があることが判明。
   • 19.0.472 で修正、しかも 18.5 より速くなった (詳細はこちら)。
2. 「H19.0.455 で PolyBevel を実行するとクラッシュする」
   • 開発側で PolyBevel を「素で」実行すれば十中八九クラッシュしない。よって再現方法が必須。これは、
     • PolyBevel を実行するとクラッシュする直前までのシーンファイルとその操作手順
       順を追っているチュートリアがあれば、その URL を添える。
     • 操作をムービーでキャプチャする (Windows の場合 Win キー+ G で可能)
   • これでも再現しない場合がある (実際しなかった)。その場合にはマシン情報などの補足情報が必要。
     • 追加情報から使用ドライバがここに表記されているドライバのバージョン (496.13) に極めて近いことが判明 -> ドライバのアップデートまたはロールバックを推奨。
       NVIDIA の場合、Houdini や他の 3D ソフトは基本的に、Game Ready Driver より Studio Driver の方が安定稼働する。
3. 「UE4.27 と Houdini Engine 19.0.455 で地形に穴を開けようとしているが開かない」
   • やろうとしていることの元になっている手順の提示
     • ドキュメントのここに Heightfieldと visibility マスクを組み合わせた方法の表記がある
     • このビデオで (24分過ぎから) 手順が紹介されている。
   • UE4 に変更があり、visibility mask の設定だけでなく Primitive Wrangle でマテリアルの追加指定が必要と判明、以下のコードを追加する。

     s@unreal_material = "Material'/Game/landscape_INST.landscape_INST'";
     s@unreal_hole_material = "Material'/Game/landscape_INST.landscape_INST'";

     実際のマテリアルで置き換える必要あり (後程、別途ページにしたい)。
4. 「UE4 Game Starter Kit の HDA が H19.0.455 で動かない」
   • 該当ページには15個のチュートリアルがあるので、どの章が問題になっているかを明記する。
     ビデオの開始時間も書いてもらえると助かる。
   • 結果、HE_Foliage_maker.hda と HE_Level_gen_WFC.hda が Python3 の Houdini で動かないことが判明。
     修正版はこちら (後程 Content Library も更新予定)。
5. 「H19.0.455 を Mac にインストールしたが起動しない」
   • Mac OS でのライセンス関連の解決策は、殆どの場合、ここにある。
     解決しない場合はライセンス診断情報が必要。

3. 補足情報

最も無難な補足情報はマシン情報である。これには

• Houdini のバージョン及びビルド番号
• OS のバージョン
• 使用しているグラフィックカード とドライバのバージョン

が含まれていて、特にドライバが問題になっているときの特定に役立つ。

インストール・ライセンス関連の場合、ライセンス診断情報が必要。

それ以外にも

• 問題を示すスクリーンキャプチャ画像 (問題部分を囲んだりするとなお良い)
• ビデオによるキャプチャ (Windows の場合 Win キー+ G で可能)

は、まさに "A picture is worth a thousand words" であり、日本語と英語の違いを超えて問題のいち早い理解に役立つ。

ここを見るとクラッシュログも含めると書いていあるが、特に Windows 版の場合、クラッシュログよりも再現方法が重要。

4. 要望

機能上の問題 (バグ) 報告と違い、機能改善要望は説明にも実装にも時間がかかる。例えば、

• 「M@ya の ○○ のような機能が欲しい」
• 「M@x の XXX のようにしてほしい」

みたいな要望は、使用者にとっては明白かもしれないが、そのソフトを使ったことが無い、もしくは昔使ったとしてももう覚えていない開発側が正しく理解するのは、ほぼ無理。

一番重要なことは、当該機能の記述よりも、

1. 何がしたいのか ("What is the problem you are trying to solve?")
2. #1 を達成する上で何が問題になっているのか ("What are the things that are getting the way?")

を明示することである。最近、「要件定義」と「要求定義」、その違いに関する記事をよく目にするようになった。いずれにせよ、これらは、限られた時間の中で簡単に書けることではなく、書けるようになるには相当の修練が必要。よって、その説明を書き出すと非常に長くなるので、別の機会に書いてみたい (書けないかもしれない)。

5. デイリービルド

Houdini はほぼ毎日デイリービルドをリリースしている。問題に遭遇した時にはデイリービルドのインストールを検討すると良い。

1. 自分の使っているビルドの番号を見る (例: 19.0.383)。
2. 今日のデイリービルドのビルド番号を見る (例: 19.0.472)。
3. 472-383 = 89 なので、383 は約3か月前のビルドとわかる。
4. Changelog / Journal を見ると、383と472の間には93ページ分の変更がある。
   • journal の見方はこちら。
   • 上記 #b 含め、Journal に出ていない変更も多数ある。
5. デイリービルドのインストールに既存ビルドのアンインストールは不要。
   インストールしたデイリービルドにメリットを見いだせないのであれば、アンインストールするだけ。

まとめ

• 送られたレポートは、サポート及び QA (Quality Assurance: 品質保証) を含め、複数の開発者が目にすることになる。
• 開発側の全員が必ずしも Houdini のすべての機能に精通しているわけではない。開発者は、大抵、自分の担当の機能以外に精通していないか他は覚えていない。
• 一回の報告では問題を完全に把握できないことが結構多い。よって、開発側から追加質問は揚げ足を取っている訳でも重箱の隅を突っついている訳でもなく、問題を正しく理解しようとしているだけ。
• よって、最も理想的な再現手順とは、最低限の Houdini 知識しか持ち合わせていない人でも再現可能な手順を提示することで、最も簡単な方法は手順を順番に書いてくこと。
• すべての問題が即解決するわけではない。問題によっては非常に時間がかかる。
• 再現できないのはバグではない。
• コミュニティページ