バグ報告ガイドライン

関連記事

• 一般的なトラブルシューティング
• ステップバイステップデバッグガイド
• デバッグ - トレースを取得

Arch Linux Bugtracker でバグレポートを開く(そして閉じる)ことはコミュニティに助力するために出来る多くの方法の内の一つです。ただし、ちゃんとしていないバグレポートは逆効果になることもあります。バグを誤って報告してしまうと、調査したり間違った報告を閉じるのに開発者は無駄に時間を割くことになります。このドキュメントはバグを効率的に報告・退治してコミュニティを手伝いたいと思っている全ての人を対象にしています。

参照: Simon Tatham による 効果的にバグを報告するには

報告する前に

詳細な整ったバグレポートを作成するのは難しいことではありませんが、報告者を代表する努力が必要になります。バグを報告する前に行うことがおそらくバグを報告することの中で一番重要な部分です。遺憾ながら、この作業にちゃんと時間をかけている人は少数です。

以下ではバグを報告したり機能を要望するのに必要な手順を示します。

重複しないか検索する

問題に遭遇したり新しい機能が必要だと思ったら、高確率で他の誰かも同じ問題やアイデアを抱えていると思って良いでしょう。もしそうなら、既に適当なバグレポートが存在する可能性があります。この場合、重複するレポートを作成してはいけません。代わりに #バグの経過観察 を見て下さい。

既存の情報を徹底的に検索してください:

• Arch Linux フォーラム: ユーザーが助けを求めたりアイデアを共有したりするのに多くの場合フォーラムが最初の停留所になります。たとえ解決方法が載っていなかったとしても、背景情報や討論によって方向性が定まるかもしれません。

• Arch Linux バグトラッカー: あなたの見つけた問題が既に Arch Linux の開発者に報告されている可能性もあります。重複するバグレポートは訳に立たないため即座に閉じられます。開いているレポートだけでなく最近閉じられたバグも検索してください。Advanced の 'search details' や 'search comments' も使用してみて下さい。検索文字列がバグのタイトルに含まれていないこともあります。

• Google やその他の検索エンジン: プログラムの名前やバージョン、(もし存在するなら)エラーメッセージの該当する部分を使って検索してください。

• 上流のフォーラム、メーリングリスト、バグトラッカー: バグの担当が Arch Linux でない場合、Arch Linux のバグトラッカーではなく上流の方へ報告するべきです。開いているレポートだけでなく最近閉じられたバグも検索してください。そのプログラムの開発版では既にバグが修正されている可能性があります。

• 他のディストリビューションのフォーラム: フリーソフトのコミュニティは広大です。Archer 以外にもアイデアを持っているユーザーはいるはずです。Gentoo フォーラム, FedoraForum.org, Ubuntu フォーラム などを検索してみてください。

上流か Arch か?

Arch Linux は GNU/Linux ディストリビューションです。Arch の開発者と Trusted User は様々なソースからソフトウェアをコンパイル・パッケージング・配布することを担当しています。上流とはこれらのソースのことを示しています – Arch Linux で配布されているソフトウェアのオリジナルの作者やメンテナなどです。例えば、人気の Firefox ウェブブラウザは Mozilla プロジェクトによって開発されています。

Arch はバグについては引き受けられません、Arch の開発者にバグを報告しても問題は解決しません。ディストリビューションの移植や統合によって発生したものでない限り、バグの対処は上流が行うべきです。

上流にバグを報告することで、Arch ユーザーや Arch 開発者の助けとなるだけでなく、全てのディストリビューションへ対策が下っていくことで、フリーソフトウェアコミュニティの他の人々にも利益をもたらします。

上流にバグを報告したり、上流からその他の関連情報を見つけたら、Arch のバグトラッカーにそのことを投稿しておけば、Arch の開発者やユーザーがそれを知ることができるので役に立つかもしれません。

それなら Arch Linux は何をするのでしょうか?

• Arch Linux のプロジェクト: pacman, AUR, mkinitcpio, Arch のウェブサイト。プロジェクトが Arch に属しているのかどうかわからないときは、パッケージ情報を表示 (pacman -Qi package_name やウェブサイトを使う) したり上流の URL を見て下さい。
  ノート: Arch Linux ソフトウェアプロジェクトの問題は、それぞれのパッケージの問題ではなく、gitlab.archlinux.org または GitHub にあるプロジェクトの上流のトラッカーで報告してください。

• パッケージング: 上流からソースコードを取得、適切なオプションを使ってコンパイル、そして Arch 環境に正しくインストールし、主要な機能が動作するか確認する。基本的にそれがパッケージングになります。Arch におけるパッケージングでは新しい機能を追加したり既存のバグにパッチをあてるというのは含まれません。これは上流の開発者の仕事です。

Arch が管理するべきないバグ・機能は、上流に報告してください。バグとはならない理由一覧も参照してください。

バグか機能か?

バグ

開発者の意向に反して、機能するはずなのに機能しないこと。

機能

ソフトウェアがすること、または誰かがコードを書いてすること。

バグとはならない理由一覧

• ソフトウェアにして欲しいこと、上流の開発者によって実装されてないこと。要するに: 新しい機能。
• 上流で既に報告されているバグ。
• 上流では既に修正されているがパッケージが最新でないために Arch では残っているバグ。
• 最新でないパッケージ。Arch のパッケージのウェブサイトにある Flag Package Out-of-Date 機能を使って下さい。
• Fedora や Ubuntu など他のコミュニティのパッチを使っていないパッケージ。パッチは上流に投稿するべきです。
• 必ずしも必須ではない機能 X や機能 Y が有効になっていないパッケージ。これは機能リクエストになります。
• .desktop ファイルやアイコンなど freedesktop のファイルが含まれていないパッケージ。こういったファイルがソース tarball に入っていない場合はバグではなく、上流に機能リクエストとして要望するべきです。ファイルが上流によって提供されているのにパッケージで使われていない場合はバグになります。

機能とはならない理由一覧

• それがバグである場合...
• Arch が機能を実装するべきではない場合、つまり上流の機能。
• パッケージが最新ではない。Arch のパッケージのウェブサイトにある Flag Package Out-of-Date 機能を使って下さい。
• Fedora や Ubuntu など他のコミュニティのパッチを使っていないパッケージ。パッチは上流に投稿するべきです。

有用な情報を集める

バグレポートで言及するべき有用な情報:

• 使用しているパッケージのバージョン。どんな場合でもパッケージのバージョンは記して下さい。"最新" や "今日の"、または "extra にあるパッケージ" などと言うのは完全に無意味です。特にバグがすぐには修正されないような場合に困ります。

• 問題に関係している場合、パッケージによって使われているメインライブラリのバージョン (PKGBUILD の depends 変数でわかります)。示すべき情報がよくわからない場合は、バグハンターがあなたに情報を指定するまで待って下さい...

• ハードウェアに関連する問題の場合、使用しているカーネルのバージョン。

• 前は機能していたのかどうか。動作しなくなってしまったのなら、いつから動かなくなったのかを記して下さい。

• ハードウェアに関連する問題の場合、使っているハードウェアのブランド名。

• 適切なログ情報がある場合はそれも追加してください。問題に応じて、以下の場所からログを取得できます:
  • systemd journal。/var/log/messages にはカーネルやハードウェアの問題に関連するログが含まれています。
  • ビデオ関連の問題 (nvidia, ati, xorg ...) の場合 ~/.local/share/xorg/Xorg.0.log や /var/log/Xorg.0.log、/var/log/Xorg.2.log など Xorg のログファイル。
  • プログラムをコンソールで動作させたり、可能であれば verbose や debug モード (プログラムのドキュメントを見て下さい) を使って、ファイルに出力をコピーしてください。ターミナルでアプリケーションを動作させるときは、多くの人が理解できるように情報を英語で表示させるようにしてください。export LC_ALL="C" を使うことで出力を英語にできます。例えば foobar という名前のソフトウェアがあって --verbose オプションを使うことができる場合、実行時に情報を表示させるには:

$ export LC_ALL="C"
$ foobar --verbose

このコマンドは現在のターミナルだけに影響を与えます。ターミナルを閉じたら効果は失われます。

dmesg の出力や Xorg のログなど、大量のテキストを貼り付けなくてはいけない場合、コンピュータにファイルとして保存してバグレポートに添付するのが好ましいでしょう。基本的に該当情報を提出するときは pastebin を使うよりもファイルを添付するほうが推奨されています。pastebin を使うとリンクが切れたり、その他の問題で中身が消えてしまう可能性があるためです。ファイルの添付は情報がこれからいつでも利用できることを保証します。

• バグの再現方法を記して下さい。これはとても重要です、人々がバグや見込みのあるパッチをコンピュータ上でテストするのに役立ちます。

• スタックトレース。実行中にプログラムによってなされたコールのリストで、バグがプログラムのどこに存在するか見つけるのに役立ちます。特にバグがプログラムをクラッシュさせるような場合に重要です。gdb (GNU Debugger) を使ってスタックトレースを取得することができます。"gdb name_of_program" でプログラムを実行してから gdb のプロンプトに "run" と入力してください。プログラムがクラッシュしたときは、gdb のプロンプトに "bt" と入力してスタックトレースを取得し、"quit" で gdb を終了してください。

バグを開く

バグか機能かの確信があり、有用な情報を全て収集したら、バグレポートや機能リクエストを開くことができます。

アカウントを作成する

Arch のバグトラッカーシステムでアカウントを作成してください。wiki やフォーラムでアカウントを作成するのと大して変わらないのでここでは特に説明することはありません。

プロジェクトとカテゴリ

機能なのかバグなのか、そして上流の問題ではなく Arch に関連することがわかったなら、適切なカテゴリで問題を投稿する必要があります (バグレポート作成ページの左上にある 'Switch' ボタンの左のドロップダウンリストのプロジェクト名を見て下さい):

• Arch Linux - testing, core, extra に入っているパッケージ用。ドキュメントやウェブサイト (AUR は除外)、セキュリティの問題も含みます。

• Arch User Repository (AUR) - AUR のウェブサイトのコードやサーバーの問題用。AUR にアクセスするために使うサードパーティのアプリやサポートされないパッケージは含まれません。

• Community Packages - community に入っているパッケージ用。サポートされないパッケージは含まれません。

• Pacman - pacman や関連する公式のスクリプトやツール用。makepkg や abs などが含まれます。yaourt などコミュニティによって開発されたパッケージは含みません。

• Release Engineering - リリースに関する全ての問題用 (ISO やインストーラなど)。

サポートされないパッケージに関する問題を報告するカテゴリはありません。AUR にはサポートされないパッケージのためにコメントを追加する機能があります。これを使ってパッケージのメンテナにバグを報告してください。

要約

簡潔にわかりやすく要約を書いて下さい。

推奨事項:

• レポートの名前を "pkgname is broken after the last update" にしないでください - 説明が足りてないばかりか "after last update" では Arch だと意味が通りません。
• 要約の冒頭は角括弧で囲ったパッケージ名にしてください、例: "[pkgname] 3.0.5-1 breaks copy-paste feature"。こういう名前のレポートにすることで開発者が簡単にレポートをパッケージ名でソートできるようになります。
• 要約にはあまり長い文章は書かないで下さい。長すぎる文章は報告リストに表示されません。

重大度

重大度を critical にしたからといってバグが迅速に解決されるというわけではありません。本当に致命的な問題をわかりにくくするだけであり、あなたのバグにあたった開発者は修正するのに聞く耳をやや持たなくなるかもしれません。

重大度の一般的な使用方法:

• Critical - システムがクラッシュしたり、多数の人に影響を与えるような重篤な起動不可、または core や外部接続するサービスのパッケージにある exploit 可能なセキュリティの問題。
• High - アプリケーションの主とする機能が動作しない、クリティカルではないセキュリティの問題など。
• Medium - 重要ではない機能が動かない、UNIX の標準が守られていないなど。
• Low - 任意の機能 (プラグインやコンパイル時に有効にする機能) が動作しない。
• Very Low - 翻訳やドキュメントの間違い。大して問題になるものではないが将来のリリースで直すべきことなど。

関連情報を含める

これはバグ報告の中で一番難しいところの一つかもしれません。有用な情報を集めるのセクションからバグレポートにどの情報を追記するか選ぶ必要があります。あなたの問題が何によるかで選ぶべきものが変わってきます。 どの情報が適切なのかわからない場合でも、遠慮する必要はありません: 必要以上に情報を提供するくらいがベターです。

バグの報告に関するチュートリアルが [1] にあります。

ただし、開発者やバグハンターはあなたに必要に応じてさらなる情報の提供を要求します。運がよければ少ないバグレポートでどの情報が必要なのかわかるでしょう。

短い情報はバグレポートの中に入れてしまってかまいません、逆に長めの情報 (ログやスクリーンショットなど) は添付するようにしてください。

バグの経過観察

バグの報告をしただけで作業が完了したとは考えないで下さい!

おそらく開発者や他のユーザーが詳細な説明を求めたり、何らかの修正方法を試すように言ってくることがあるはずです。フィードバックが継続して得られなければ、バグを閉じることが出来ず、結果としてユーザーと開発者の両方を怒らせることになるでしょう。

投票と監視

大事だと思うバグには投票することができます。投票の数によって、そのバグの影響を受けている人数を開発者に示します。ただし、投票はバグを解決するのに効果があるわけではありません。あなたがオリジナルの報告者でない場合、バグについてあなたが知っている追加情報を投稿することのほうがより重要です。

バグの監視は重要です - バグの状態が変更されたり新しいコメントが追加されるとあなたのところにメールが送信されます。バグを開いたときは、"Notify me whenever this task changes" のチェックを入れてメールを受け取るようにしてください。

追加情報のリクエストに応える

人々は時間をかけてあなたのバグレポートを見て、それからあなたを助けようとするでしょう。バグを解決する手助けは続けなければなりません。質問に答えないと、バグが解決されないままになるだけでなく修正しようとしている人の邪魔になる可能性もあります。

リクエストを受けたら情報を提供するようにしてください、解決方法を提示されたら試して下さい。

何週間・何ヶ月かたっても質問に答えないとあなたの作成したバグは開発者やバグハンターによって閉じられるでしょう。

該当ソフトウェアの新しいバージョンが出たらバグレポートを更新する

場合によっては特定のパッケージバージョンにあるバグが新しいバージョンで修正されていることがあります。このようなときはバグレポートのコメントでそのことを知らせて、バグを閉じるように要求してください。

解決したら閉じる

バグを報告するだけして解決してもそのことを知らせないと、既に存在するはずの解決方法を探している人を置き去りにすることになります。解決方法を見つけたらバグレポートのコメントに解決方法を載せて、バグを閉じるようにリクエストしてください。

バグの状態について

バグは複数の状態を通過します:

• Unconfirmed - デフォルトの状態です。報告されたばかりで誰も問題を再現しておらず、実際にバグであるかの確認がなされていません。

• New - バグとして確認されていますが、該当ソフトウェアを担当している開発者にバグが割り当てられていません。通常はバグの原因がどのソフトウェアなのか見極めるためにさらなる調査が必要な状態を示します。

• Assigned - バグが関連するソフトウェアを担当しているしている開発者にバグが割り当てられています。バグを修正するのがその開発者一人であるというわけではありません。また、その開発者が解決方法を導くということでもありません。ただ単に、開発者がバグのライフサイクルを処理するというだけです。パッチのレビューをしたり、修正をリリースしたり、必要ならばバグを閉じるなどがその仕事です。バグを素早く修正してもらおうと開発者に直接連絡を取ったとしても意味がありません。おそらく連絡されるのを好まないでしょう...

• Researching - 誰かが解決方法を探しています。この状態が Arch で使われることは稀でそのほうがベターでしょう。researching 状態はそのバグレポートに関心を持たなくても良いと人々を信じさせるかもしれません。しかしながら、通常はバグを修正するのには複数の人が必要になります: バグに成通している人が複数いるほうが助かります。

• Waiting on Response と Requires testing - バグを報告した人に対して、さらなる情報を提供したり提案された解決方法を試すように要求が出ているが、まだフィードバックが送られていない状態です。この2つの状態が Arch で使われることは稀でもっと頻繁に使うべきでしょう。ただし開発者やバグハンターがコメントで質問を投げることがあるのでバグを監視 (投票と監視セクションを参照) することは重要です。

• A task closure has been requested - 正確にはこれは状態ではありませんが、いくつかのバグレポートでこのような公示がされているのを見つけるかもしれません。この状態は誰かがバグを閉じるようにリクエストしていることを示しています。大抵はリクエストに理由が加えられています。バグを閉じるかどうかは割り当てられた開発者次第です。

• Closed - 正当なバグではなかった (バグとはならない理由一覧を参照) もしくは解決方法が発見・リリースされています。

開発者や TU などがバグの状態を変更します。