新しい問題の提出¶

優れた問題報告やバグ報告を作成することは、問題のトラブルシューティング能力に決定的な差をもたらします。以下に、BeeWareに適切なバグ報告を提出する方法をご紹介します。

既存の問題を検索する¶

新しい問題を提出する前に、インデックスを検索して既存の問題と一致するものがないか確認してください。問題が一致しそうな既存の未解決問題がある場合は、その問題にコメントを追加し、自身の経験に関する追加情報を記載してください。例えば、異なるPythonバージョンや異なるオペレーティングシステムで問題が発生している場合、その追加情報は問題の影響範囲や原因の特定に役立ちます。

問題に一致しそうなクローズ済みの課題を見つけた場合、その課題がいつクローズされたかを確認してください。課題がごく最近クローズされた場合、そのバグは修正済みであり、次回のリリースで修正される可能性が高いです。課題が4ヶ月以上前にクローズされている場合、たとえエラーメッセージが似ていても、あなたが経験しているのは別の問題である可能性が高いです。

該当する問題が見つからない場合は、新しい問題を報告するのが適切かもしれません。

議論から始めましょう¶

GitHubで問題報告を提出する前に、まずディスカッションを開始して、経験している現象が実際にバグなのか、それとも設定やプロセスの問題なのかを確認することを検討してください。文書化された動作と直接矛盾する挙動を目撃している場合を除き、バグ報告を直接提出する前に質問を投げかける価値があるでしょう。もし実際に問題を発見したことが判明した場合、ディスカッショントピックは簡単に問題報告に変換できます。

議論を始めることは、問題を最適な場所で報告していることを確認するのにも役立ちます。BeeWareの使用中に問題が発生したとしても、その問題はBeeWareエコシステム内の別のプロジェクトのバグが原因である可能性があります。

良いバグレポートの書き方¶

新しい問題が必要な場合、可能な限り詳細を提供することが重要です。優れたバグ報告には、バグに関連する可能性のあるすべての情報と、再現可能な最小限の例が含まれます。

再現例は、バグを再現できる最小限の簡潔なコードで構成すべきです。大規模な例を提供すると、特に他のライブラリに依存している場合や、期待される動作や内部ロジックに関する深い知識が必要な場合、トラブルシューティングが著しく困難になります。

可能な限り詳細な情報が必要です。これには以下が含まれますが、これらに限定されるものではありません：

お使いのオペレーティングシステムのバージョン - マイクロバージョンまで（例: macOS 15.7.2）。
Pythonのバージョン（マイクロバージョンまで含みます。例：3.14.1）。
Pythonのインストール方法について。python.orgからダウンロードしましたか？Homebrewを使いましたか？uv？pyenv？conda？それとも他の方法ですか？
使用しているBeeWareツールの具体的なバージョン（例：Toga 0.5.3）を教えてください。開発版を使用している場合、どのGitハッシュを使用していますか？「現在のメインブランチ」というだけでは不十分です。なぜなら、それは日々変更される可能性があるからです。
問題を引き起こすためにインストールが必要な他のパッケージの具体的なバージョン。この情報を提供するには、python -m pip freezeの実行結果を含めることができます。
ログファイルが生成されている場合、そのログファイルの全体。
スタックトレースが生成されている場合は、完全なスタックトレースを提供してください。最終的なエラーメッセージだけを提供するのではなく、スタックトレースの完全なコンテキストが重要です。また、これをテキスト形式で提供することが最善であり、スクリーンショットとして提供しないでください。
この問題に影響している可能性のある、お使いのコンピューターやネットワーク設定に関するその他の情報をお知らせください。お使いのコンピューターは古いものや動作の遅いものですか？ファイアウォール、ウイルス対策ソフト、その他の制限が設定されている職場の端末ですか？ネットワークの速度が特に遅いですか？オペレーティングシステムを、通常とは異なるシステムデフォルト（非常に大きなフォントやその他の支援技術が有効になっているなど）で実行していますか？

枠にとらわれずに考え、経験している問題に影響を与えそうな要素はすべて含めてください。必要以上に情報を提供いただいても、不要な部分は簡単に除外できます。しかし、あなたが省いた要素については、我々も解決策を導き出せません。

最小限の例¶

バグ報告で最も重要なのは最小限の再現ケースです。第三者が再現手順を読み、その手順に従って同じ問題を再現できる必要があります。そのためには、問題が発生するサンプルプロジェクトを提供するか、既存のコードベースに含まれるチュートリアルやサンプルプロジェクトなど、既存の例を利用するのがより望ましいでしょう。

プロジェクト全体は最小限の再現ケースではありません。最小限の再現ケースには、問題の再現に絶対に必要でないコードは一切含めるべきではありません。再現ケースの作成には徹底的に厳格に臨んでください。問題の再現に不要なボタンがあれば、そのボタンは含めないでください。

この最小限の再現ケースを開発する過程で、問題の原因が明らかになることがよくあります。なぜなら、最小限の例を作成する行為自体が、問題の根本原因を正確に特定することを迫るからです。それがコードのバグなのか、誤った前提やAPIの使用に起因するものなのかを。

再現手順についても明確に記載すべきです。「サンプルアプリを閉じる」という指示は、ウィンドウの閉じるボタンをクリックすること、メニューから「終了」を選択すること、ターミナルでControl-Cを入力することなど、複数の操作を意味する可能性があります。問題の再現に必要な操作について、報告文に曖昧さが残らないようにしてください。

レポートの提出¶

プロジェクトの問題リストに移動し、「新規問題」ボタンをクリックして「バグ報告」を選択すると、プロセスが開始されます。

問題報告テンプレートの全項目を必ず記入してください。テンプレートは必要な情報を提供するためのガイドとして用意しています。テンプレートで要求されている情報以上に（むしろそうすべきです！）詳細を記載することは可能ですが、最低限、テンプレートに記載されている情報は全て必要です。

コードを含める場合、BeeWareチュートリアルなどの既存の例で再現できる場合はリンクを提供してください。そうでない場合は、レポート内にコードを記載してください。Markdown形式で記述する必要があります。コードブロックは、前後に3つのバッククォート（```）で囲みます。

長いテキストブロックを含める必要がある場合、以下の構文を使用して折りたたみコンテンツにできます：

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

可能な限りの情報を入力したら、「作成」をクリックしてレポートを送信してください。