How to write useful bug reports/jp

有益なバグレポートの書き方

　バグ報告は、当フォーラムやIRCではなく、必ずRawTherapee Github issue trackerで行って下さい。

　私たちは“バグ報告”という用語を広義に使っていますので、どの様な問題に関しても以下に示す詳細を必ず提供して下さい。

1 有益なバグレポートに必要な事項

• 　貴方が使用しているRawTherapeeの詳しいバージョン情報。バージョン情報は、をクリックし、右下の“RawTherapeeについて．．”をクリック、そして“バージョン”のタブを開けば入手できます。殆どの場合、多くの情報が入っていますので、それら全てをコピーしてバグレポートに貼り付けます。もしも情報がない場合、バージョンを知るにはメイン画面左上のタイトルバーを見て下さい。
• 　貴方が使用しているオペレーティングシステムの名前とバージョン
  • 　Windowsの場合は、（スクリーン）キーボードからのショートカット、⌘ Win+⎉ Pauseで見つけることが出来ます。
  • 　Linuxの場合は、ターミナルでuname -aを入力すれば見つけることが出来ます。
• 　問題が発生するまでの正確な手順を説明して下さい。画像を“ニュートラル”処理プロファイルで開き、問題が発生するまで貴方が行った操作の手順です。
• 　Rawファイルとpp3ファイルのアップロード。バグが発生した時のrawファイルとPP3ファイルが常に必要（rawファイルの問題なのか、処理設定が問題なのか、或いはそのrawファイルがサポートされていない種のものなのか、見極める必要があるため）になりますので準備しておいて下さい。それをwww.filebin.net（英語）のようなファイルシェアリングサービスにアップロードします。
• 　問題が発生した時の画面のスクリーンショット。その際、切り抜きは行わないで下さい。RawTherapeeのウィンドウ全体が表示されたスクリーンショットを送って下さい。
• 　“バグごとに一件”、或いは機能要請ごとに一件、の形で問題を報告します。一つの報告の中で異なるバグ修正や、異なる機能要請はしないで下さい。

　加えて、次のような作業も多くの場合役に立ちます：

• 　問題発生をビデオに記録したものです。スクリーンショットや“問題の再現”手順だけでは、その問題を上手く説明できない場合に有効です。以下のフリーソフトを使えば簡単に作成できます。
  • 　Windowsの場合は：ShareX
  • 　Linuxの場合は：SimpleScreenRecorder
• 　バグレポートを作成する前に、私たちのフォーラムや問題事項をチェックして下さい。既に他の方が同じ問題を報告しているかもしれません。同じ問題であれば、レポート作りが無駄になってしまいます。
• 　貴方が使っているRawTherapeeのバージョンが最新のものであるか確認して下さい。それ以前のバージョンにあったバグが原因で問題が発生していたのであれば、最新バージョンで既に解決されている可能性があります。
• 　貴方が抱える問題がプログラムのクラッシュの場合、出来ればスタックバックトレースを送って下さい。どの様にスタックバックトレースを手に入れるかは以下で説明します。それが難しい場合は少なくとも上記に関する最新情報を提供して下さい。そうでないと折角作成したバグレポートは役に立たないかもしれません。

　バグレポートについてもっと知りたい方は、以下のサイトを参照して下さい：http://www.chiark.greenend.org.uk/~sgtatham/bugs.html

2 RawTherapeeがクラッシュした時点を特定－スタックバックトレースの紹介

　スタックバックトレースは、特定ポイントまでのプログラム動作の経過記録です。私たちとしては、RawTherapeeがクラッシュした時点までの動作経過を知る必要があり、それを精査することでバグを取り除き、クラッシュの問題を解決します。私たちは自分たちのシステムで安定していると認められたビルドを安定バージョンとしてリリースしていますが、貴方のシステムではクラッシュするのであれば、貴方から有益な情報を手に入れ、場合によっては自分たちでそのクラッシュを再現するなどして、バグの修正を行います。スタックバックトレースはその意味で非常に有益な情報なのです。

　プログラムを動作させるためにコンパイルが必要です。一般的に2つの方法があります：

• 　一つは処理速度の最適化が図られている“リリース”バージョンを使う方法ですが、問題がクラッシュの場合はこのバージョンからは殆ど有益な情報が得られません。
• 　一方、“デバッグ”バージョンを使う方法では有益な情報がたくさん得られます。但し、プログラムの動作速度は著しく遅くなります。

　リリースバージョンを使う方法でも多少の情報が得られる可能性はありますが、情報の量や質はデバッグバージョンを使う方がリリースバージョンを使うより遥かに勝っています。RawTherapeeの“リリース”バージョンも“デバッグ”バージョンも、当フォーラムやダウンロードページから手に入ります。プログラムを普通に使うならば、処理速度の速いリリースバージョンを使って下さい。もしもクラッシュの問題が発生したら、私たちに有益な情報が伝わるように、デバッグバージョンを使って下さい。私たちがその情報を使ってバグの修正を行います。

　デバッグバージョンの入手：

• 　Windows用のプログラムをインストールした場合は、その中に“リリース”バージョンrawtherapee.exeと“デバッグ”バージョンrawtherapee-debug.exeの両方の実行プログラム（エグゼファイル）が入っています。
• 　Linux用のプログラムは、名前の中に“debug”が入っていない限り、一般的には“リリース”バージョンですが、貴方のディストリビューションやパッケージマネジャー、パッケージのソース次第ではその限りではありません。最良の方法は自身でコンパイルすることです；Linuxのコンパイリングの説明を参照して下さい。簡単です。
• 　macOS用のプログラムは今のところ“リリース”バージョンの実行ファイルしか含まれていませんが、将来、“デバッグ”バージョンを入れたいと思います。

2.1 デバッグバージョン入手法

　私達のダウンロードページから、或いは貴方のパッケージマネジャーから、最新バージョンのデバッグビルドを探しますが、もし見つけられなかったら（実際には、普通見つからないでしょう）、私達にお尋ねいただくか、自らデバックバージョンを作ります。OSがLinuxであれば、非常に簡単です。Linuxによるコンパイリングの解説を参照して下さい。時々、“release”バージョンでも、幾らかの情報を得ることが出来ますが、デバッグバージョンを使う方が、はるかに有効です。

　ソフトウェアの動作というものは、デバッガーがあることで、通常環境における動作と異なる動きを示すことがよくあります。これはデバッガーがあることで、アルゴリズムの内部で働くタイミングに影響が出るからです。ですから、GDB（これもデバッガー）からRawTherapeeを動かした時、それが原因で通常使用では起こらなかったバグ（クラッシュ）に直面するかもしれません。始末に負えない困った事実ですが、幸いなことに、そういったケースはごく稀なので、進んでデバッグバージョンを手に入れて下さい。そして、貴方が悩まされていたクラッシュを再現すれば、今度は有効なスタックバックトレースが得られます。

　また、バグレポート提出をする前に、常に、ダウンロードしたプログラムが最新バージョンであることを確認してからお願いします。旧バージョンのバグが、新バージョンで既に解決済みになっている可能性があるからで、時間の無駄になってしまいます。

3 ステップバイステップ

1. GDBをインストールします。どの様に行うかは、貴方のOSとディストリビューション次第です。
   • Linuxの場合は、パッケージマネジャーを使います。

     Ubuntuの場合は、ターミナルを開き、以下の様に書き込みます：

     sudo apt-get install gdb

     Gentooの場合は、以下の様に書き込みます：

     sudo emerge gdb

   • Windowsの場合は、TDM-GCC（英語）をインストールし、その際にGDBのパッケージも同時にインストールします。gdb.exeをコピーし、RawTherapeeのディレクトリーに貼り付け、rawtherapee.exeと一緒の場所に置きます。
   • MacOSXに関しては、私達は不確かなので、GDBのインストールの方法を知っている方がいたら、是非私達までご連絡下さい。
2. GDBからRawTherapeeを起動します。
   • Linuxの場合、貴方がRawTherapeeのビルドでデバッグバージョンをコンパイルし、そのデバッグビルドが~/rt_default_Debug/であると仮定すれば、次を入力します：

     gdb ~/rt_default_Debug/rawtherapee

   • Windowsの場合は、コマンドプロンプトを開き、貴方のRawTherapeeディレクトリーを誘導します。仮に実行可能なRawTherapeeデバッグのファイル名が、“rawtherapee-DEBUG.exe”だとしたら、次を入力します：

     gdb rawtherapee-DEBUG.exe

3. GDBが起動し、RawTherapeeが動作する準備ができたので、次を入力します：

   r

4. RawTherapeeが動作を始めるとGDBに以下のような情報が次々と現れます：

   [New Thread 0x7fffa7b2e700 (LWP 11532)]

   [New Thread 0x7fffa9b32700 (LWP 11533)]

   [Thread 0x7fffaab34700 (LWP 11528) exited]

   [Thread 0x7fff97dfd700 (LWP 11507) exited]

   クラッシュに直面した操作を行い、RawTherapeeをクラッシュさせます。プログラムは動かなくなりますが、画面はそのままです。クラッシュしたかどうかは、画面の全てが応答しなくなったことで判断できます。Alt+TabでGDBのターミナル画面に戻ります。

5. 私たちとしてはスタックバックトレースの詳細が欲しいので、それを簡単に行うため次の3つのコマンドを使って、GDBにそれらをlog.txt（名前は何でも構いません）に保存させます。次のように入力します：

   set pagination off

   set logging file log.txt

   set logging on

6. 　GDBに全てのスレッドを表示させ、実際のスタックバックトレースを出力させます。次のように入力します：

   info threads

   thread apply all bt full

   スクリーンに沢山のテキストや数値、コード、記号が表示されるでしょう。これらがlog.txtに保存されます。

7. 　ここでGDBを停止させます。次のように入力します：

   　q

   　確認します

   　y

8. 　これでバグ報告を行う準備が整いました。Github bug trackerでバグ報告を行って下さい。log.txtファイルを添付し、クラッシュが発生した時の手順を上記で説明した詳細と共に私たちに送って下さい。

　体裁がきれいに整ったテキストは読みやすいものです。GitHubにコードを貼り付ける際は、バッククォート或いは字下げを使って下さい-GitHubのガイド。当フォーラムにコードを貼り付ける場合も、バッククォート或いは字下げを使って下さい-フォーラム。

　繰り返しになりますが、をクリックし、環境設定→RawTherapeeについて→バージョンに記述されている内容、raw画像のサンプル、pp3ファイル、貴方のオペレーティングシステムの情報（CPU、速度、RAM容量）をレポートに載せることをお忘れなく。