ツールの使用¶

私たちが得られる最も貴重なフィードバックの一つは、BeeWareツールを使用しようとした人々が、操作上の摩擦点や不足している機能を発見した際のものです。ツールを実際の業務で利用する際に直面する可能性のある困難を理解することは、私たちにとって非常に有益です。

ずっと作りたかったものを思い浮かべて、実際に作ってみてください。もしそのプロジェクトを完成させることができたなら、おめでとう！あなたはついに、ずっと欲しかったものを手に入れたのです。

ただし、もしうまくいかなかった場合は、何が問題だったのかお知らせください。不足している機能はありましたか？ドキュメントが分かりにくい、あるいは不十分な点はありましたか？皆様の体験を共有いただくことで、計画プロセスを形作る上で役立つ貴重な知見を得ることができます。

問題が発生した場合は、新しいディスカッショントピックを立ててください。新たな問題や機能提案の始まりとなる可能性があります。

貢献ツールの使用状況¶

新しい問題を報告する

優れた問題報告やバグ報告を作成することは、問題のトラブルシューティング能力に決定的な差をもたらします。以下に、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>

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

新機能の提案

BeeWareの改善案をお持ちですか？そのアイデアをどのように提案すれば検討してもらえますか？

調査を行ってください¶

最初のステップは、BeeWareの課題トラッカーで既存の機能課題（「enhancement」タグ付き）、ドキュメント課題（「documentation」タグ付き）、またはディスカッションスレッドを検索し、そのアイデアが以前に提案されていないか確認することです。既に存在する場合、新たな情報またはアイデアを追加できる場合は、既存のスレッドにそれらを含めてください。調査の支援が必要な場合は、BeeWare Discordの#devチャンネルでお尋ねください。既存スレッドの方向性を示したり、ご存知ないかもしれない背景情報を提供したり、一見関連性がないと思われる別のアイデアとあなたのアイデアを結びつけることができるかもしれません。

その考えについて話し合う¶

既存のアイデアに関する参照が見つからない場合は、ディスカッションスレッドを開始してください。アイデアの目的とユースケースについて概要を説明してください。実装された場合の機能の外観に関する考え（APIの一般的な形状、機能の視覚的表現、追加されるドキュメントなど）も記載してください。該当する場合は、アイデアが異なるプラットフォームでどのように実現されるかについての調査結果も記載してください。

ディスカッションスレッドが開設されると、BeeWareチームとコミュニティの他のメンバーが対応します。コアチームは、ご提案いただいたアイデアについて、少なくとも2営業日以内に最初の印象を提供することを目指します。アイデアが特に複雑な場合、より詳細な分析には最大1週間かかる可能性があります。休日やカンファレンスなどのイベントにより、これらのスケジュールが若干遅れる場合があります。

これはあなたのアイデアについて議論に参加する機会です。詳細や背景情報の提供をお願いする場合があります。コミュニティの他のメンバーも議論に加わり、異なる視点や提案、対案を提示することがあります。この議論の結果が今後の進め方を決定します。

すべてのアイデアが受け入れられるわけではないことを理解することが重要です。このプロセスが提案から始まるのは、変更が受け入れられない理由があるのに気づくまで、すべての作業を無駄にさせないためです。

これは良いアイデアではなかったという意味ではありません！技術的な理由で実装できない場合もあるのです。例えば、次のような理由でアイデアを却下する可能性があります：

すべてのサポート対象プラットフォームで確実に実装することは困難、あるいは不可能である；または
維持が困難であるか、あるいはその維持には広く普及していない技術やソフトウェアへのアクセスが必要となる。
特定のユーザー層にサービスを提供するが、他のユーザーに大きな負担を強いる。

もしあなたのアイデアが適切でないと判断した場合でも、必ずしもそのアイデアを諦める必要はありません。特定のアイデアを却下する一方で、プラグインインターフェースやその他の拡張ポイントを追加することで、同じ機能を外部ライブラリとして維持できるようにする案には、はるかに柔軟に対応できる可能性があります。そうすれば、その機能自体は維持しつつ、特定のメンテナンス上の懸念や、機能がプロジェクト自体の制約となるような制限を回避できるのです。

正式な機能リクエストに変換する¶

機能の形式について議論が合意に達したら、beeware課題管理システムで新しい機能リクエスト課題を作成し、議論を要約するとともに、背景説明として議論へのリンクを記載してください。

ご自身の機能提案を必ずしもご自身で実装する必要はありません。提案内容の詳細を記載したイシューを開くことができます。ただし、単にイシューを投稿したからといって、それが必ず実装されるわけではありません。同じ機能に関心を持つ他のコミュニティメンバーやコアチームメンバーが取り上げてくれる可能性を待つ必要があります。ただし、それが必ず実現する保証はありません。確実に実装したい場合は、ご自身で実装するか、他の人に実装を依頼する必要があります。