問題の修正¶

BeeWare は既知の問題のリストを追跡します。これらの問題はいずれも、対応すべき候補となります。

このリストは様々な方法でフィルタリングできます。例えば、プラットフォームでフィルタリングすれば、テスト可能なプラットフォームに影響する課題に集中できます。あるいは、ドキュメントバグなどの課題タイプでフィルタリングすることも可能です。また、初心者向け課題用のフィルターも用意されています。これらは原因が特定されている問題として認識されており、修正は比較的容易であると考えられています（ただし、分析が誤っている可能性もあります）。

問題が6か月以上経過している場合、その問題は既に解決されている可能性が十分にあります。そのため、まず最初に問題が再現可能かどうかを確認してください。バグレポートに記載されている情報を使用して、問題の再現を試みてください。問題が再現できない場合は、その発見内容を問題へのコメントとして報告し、別の問題を選んでください。

問題を再現できるなら、修正を試みてください！その機能を実装しているコードの組み合わせを特定し、何が正しく動作していないのかを突き止められるか確認してください。

たとえ問題を修正できなくても、その過程で発見したことはすべて、問題報告へのコメントとして報告する価値があります。問題の原因は特定できたが修正方法はわからない場合でも、その知識は、そのプラットフォームに詳しい人が問題を解決するのに十分な情報となることがよくあります。問題報告に再現ケース（問題だけを再現する最小限のサンプルアプリ）がまだ提供されていない場合、それを提供することは非常に大きな助けとなります。

問題修正の貢献¶

開発環境を構築する

BeeWareへの貢献には、開発環境のセットアップが必要です。

前提条件¶

以下の前提条件をインストールする必要があります。

macOSLinuxWindows

BeeWare は Python 3.10+ が必要です。また、仮想環境を管理する手法（例：venv）も必要です。

インストール済みのPythonのバージョンを確認するには、次のコマンドを実行します：

Python 3.8.10 (デフォルト、2020年7月20日 16:16:00)

複数のPythonバージョンがインストールされている場合、python3を特定のバージョン番号（例：python3.13）に置き換える必要がある場合があります。

最近リリースされたバージョンのPython（例：3.14.0のような「.0」または「.1」のマイナーバージョン番号を持つバージョン）の使用は避けることを推奨します。これは、macOS上でPythonをサポートするために必要なツールが、通常、最近リリースされた安定版のPythonバージョンでは利用できない場合が多いからです。

BeeWare は Python 3.10+ が必要です。また、仮想環境を管理する手法（例：venv）も必要です。

インストール済みのPythonのバージョンを確認するには、次のコマンドを実行します：

Python 3.8.10 (デフォルト、2020年7月20日 16:16:00)

複数のPythonバージョンがインストールされている場合、python3を特定のバージョン番号（例：python3.13）に置き換える必要がある場合があります。

Pythonの最近リリースされたバージョン（例：3.14.0のような「.0」または「.1」のマイナーバージョン番号を持つバージョン）の使用は避けることを推奨します。これは、Linux上でPythonをサポートするために必要なツールが、通常、最近リリースされた安定版Pythonバージョンでは利用できない場合が多いからです。

BeeWare は Python 3.10+ が必要です。また、仮想環境を管理する手法（例：venv）も必要です。

インストール済みのPythonのバージョンを確認するには、次のコマンドを実行します：

C:\...>py -3 --version

複数のバージョンのPythonがインストールされている場合、-3を特定のバージョン番号（例：-python3.13）に置き換える必要がある場合があります。

Pythonの最近リリースされたバージョン（例：3.14.0のような「.0」または「.1」のマイナーバージョン番号を持つバージョン）の使用は避けることを推奨します。これは、Windows上でPythonをサポートするために必要なツールが、通常、最近リリースされた安定版Pythonバージョンでは利用できない場合が多いからです。

開発環境を設定する¶

BeeWareの開発環境を設定する推奨方法は、仮想環境を使用し、その後BeeWareの開発版とその依存関係をインストールすることです。

BeeWare リポジトリをクローンする¶

次に、GitHub上のBeeWareページに移動し、まだ行っていない場合は、リポジトリをフォークして自分のアカウントに追加してください。次に、フォークしたリポジトリの「<> コード」ボタンをクリックします。お使いのコンピュータにGitHubデスクトップアプリケーションがインストールされている場合は、「GitHub Desktopで開く」を選択できます。そうでない場合は、表示されたHTTPS URLをコピーし、コマンドラインを使用してリポジトリをコンピュータにクローンします：

macOSLinuxWindows

BeeWare リポジトリをフォークし、その後：

$ git clone https://github.com/<あなたのユーザー名>/beeware.git

(あなたのGitHubユーザー名をここに置き換えてください)

BeeWare リポジトリをフォークし、その後：

$ git clone https://github.com/<あなたのユーザー名>/beeware.git

(あなたのGitHubユーザー名をここに置き換えてください)

BeeWare リポジトリをフォークし、その後：

C:\...>git clone https://github.com/<あなたのユーザー名>/beeware.git

(あなたのGitHubユーザー名をここに置き換えてください)

上流リポジトリを設定する¶

フォークをクローンした後、BeeWareリポジトリをupstreamリモートとして追加してください。これにより、ローカルクローンが元のリポジトリを参照できるようになり、時間の経過に伴う更新の同期が容易になります。

また、TogaやBriefcaseなどのツールが正確なバージョン番号を解決できるように、upstreamからのタグも必要です:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

フォークにそれらのタグも追加したい場合は、プッシュできます:

$ git push --tags

後で新しいクローンを作成し、フォークからタグを利用できるようにしたい場合に便利です。

仮想環境を作成する¶

仮想環境を設定し、pip をアップグレードするには、以下を実行してください：

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

プロンプトには現在、前に (.venv) プレフィックスが付いているはずです。

インストール BeeWare¶

ソースコードを入手したので、開発環境に(https://setuptools.pypa.io/en/latest/userguide/development_mode.html)を[編集可能なインストール]BeeWareできます。次のコマンドを実行してください：

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

コミット前の検証を有効にする¶

BeeWareでは、単純な問題の特定やコードフォーマットの標準化のためにpre-commitというツールを使用しています。これは、gitフックをインストールすることで実現され、gitコミットを確定する前に一連のコードリンターを自動的に実行します。pre-commitを有効にするには、以下を実行してください：

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

さあ、BeeWareのハッキングを始めましょう！

ブランチから作業する

変更作業を始める前に、必ずブランチを作成してください。デフォルトでは、リポジトリのフォークをクローンすると、main ブランチがチェックアウトされます。これは BeeWare の main ブランチの直接コピーです。

main ブランチからプルリクエストを送信することは可能ですが、そうしない方が望ましいです。ほぼ正しいプルリクエストを送信した場合、レビュー担当のコアチームメンバーは、小さな変更を求めるフィードバックを与える代わりに、必要な修正を加えられる可能性があります。しかし、main ブランチからプルリクエストを送信すると、レビュー担当者は修正を加えられなくなります。

メインブランチで作業すると、最初のプルリクエストを完了した後のあなた自身にとっても困難になります。2つ目のプルリクエストに取り組む場合、2つ目の貢献の基盤となるアップストリームプロジェクトのメインブランチの「クリーンな」コピーが必要になります。最初の貢献をmainブランチから行った場合、そのクリーンなバージョンはもはや利用できません。

その代わりに、変更は 機能ブランチ で行うべきです。機能ブランチには、行った変更を識別するためのシンプルな名前が付けられます。たとえば、Windows 11でのビルドに問題を引き起こすバグを修正する場合、fix-win11-buildというフィーチャーブランチを作成します。バグが報告済みの特定の課題に関連している場合は、ブランチ名にその課題番号を含めることも一般的です（例：fix-1234）。

fix-win11-build 機能ブランチを作成するには、次のコマンドを実行します:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

問題を再現する

そもそも問題が存在しなければ、それを修正することはできません。したがって、問題を再現することは、それを修正するための前提条件です。ソフトウェアにおいては、問題は一般的に「バグ」と呼ばれ、問題報告は「バグ報告」と呼ばれることが多いです。

誰かがバグ報告を提出しました。報告者が説明している手順が、実際に報告されているバグを引き起こしていることを確認する必要があります。報告に記載されている内容を正確に再現することで、同じ結果を再現できますか？再現できない場合は、その理由を特定する必要があります。

コード内のバグ¶

理想的な状況では、バグを報告した人物と同じ環境設定を持ち、手順に従い、説明通りにバグを再現できるはずです。しかし多くの場合、そう単純にはいきません。多くのバグ報告には、曖昧な説明と漠然とした条件設定しか記載されていません。問題は、多くのバグが関与する条件セット（操作方法、様々な前提条件、OS、OSバージョン、CPUアーキテクチャ、あるいはユーザーのマシンが古くて遅いか新しく速いかなど）によって変化する点にあります。バグを取り巻く状況に関する情報が豊富であればあるほど良いのです。報告者が提供した条件セットを再現してみてください。それができない場合、次のステップとして、バグを報告した人物に追加情報の提供を依頼する必要があるかもしれません。

バグを再現する最良の方法は、問題が再現される最小限の例を用いることです。多くの場合、報告者は最小限の実行可能な例を提供しません。仮に例を提供したとしても、それは「実環境」のアプリケーションから直接コピーされたものになるでしょう。あなたの目的は、問題を再現する最小限の形式に報告内容を簡素化することです。最良の再現ケースは最小限のプログラムです。この簡素化自体も有益であり、実際の問題点を特定します。誰でも最小限の例を実行すれば、報告されたバグを再現できるのです。

ドキュメントのバグ¶

ドキュメントのバグは様々な形で現れる。書式設定の問題により表示上の不具合が生じる場合があります。時にはバグではなく、ドキュメントの誤読や単純なミスであることもあります。とはいえ、ドキュメント自体に問題がないとは限りません。内容が不明確または不正確で、混乱や誤解を招く余地があるのです。説明すべき概念が完全に未記載であるため、議論されていない可能性もあります。

ドキュメントの問題でバグが報告された場合、実際に問題がまだ存在しているか確認する必要があります。レンダリングの問題の場合は、ドキュメントをビルドして問題を再現できるか確認してください。コンテンツの問題は、更新が提出されていないか読み込んで確認する作業です。

問題を更新する¶

トリアージプロセスの最終ステップは、問題にコメントを残すことで調査結果を記録することです。

問題が説明通りに再現できる場合は、その旨を伝えるだけで十分です。元の報告者が説明した通りの方法で、同じ問題が発生していることを確認した旨をコメントに残してください。

追加のコンテキストを提供できる場合は、その詳細を含めてください。これには、異なるオペレーティングシステム上での問題の再現、関連ソフトウェアの異なるバージョンでの再現、または元の報告内容と異なる点全般が含まれます。

元の報告に必要な再現手順の詳細が不足している場合は、それらの詳細を含めてください。これには、元の報告に記載されていないオペレーティングシステムやバージョン情報、より完全なログやスタックトレース、問題の再現に必要な正確な操作手順の明確な指示などが含まれます。問題の再現をより簡便な方法で確立した場合（または元の報告者が再現ケースを提供していない場合）、その再現方法の詳細を含めることができます。

問題が再現できない場合も、試した内容を詳細にコメントしてください。問題が「存在しない」場所を把握することは、問題が「存在する」場所を把握することとほぼ同等に重要です。なぜなら、それが原因の絞り込みに役立つからです。問題が再現できない理由についての仮説がある場合（例えば、使用方法の誤りによるものと考えられる場合や、最近のOSアップデートで問題が解決された可能性がある場合など）、その推測もコメントの一部として含めてください。

最後に、コアチームに対してご提案があればお寄せください。元の報告に誤りがあると思われる場合は、その問題をクローズすべきだと提案してください。問題の原因について仮説をお持ちの場合は、それも提案できます。皆様のご意見は、コアチームが問題を次の段階に進める方法を検討する上で役立ちます。

問題の修正にコードの変更が必要な場合：

コードを記述し、実行し、テストする

バグの修正や機能の実装には、新しいコードを書く必要があります。

BeeWareのコード作成に関するガイドラインをまとめたコードスタイルガイドを用意しています。

テスト駆動開発¶

コードが期待どおりに動作することを確実にする良い方法は、まずそれを検証するためのテストケースを作成することです。テスト対象のコードはまだ存在しないため、このテストケースは当初は失敗するはずです。その後、テストに合格するために必要なコードの変更を加えれば、自分が書いたコードが期待通りの問題を解決していることが確認できます。

コードを実行する¶

コードを記述したら、それが正常に動作することを確認する必要があります。期待どおりに動作しているかを確認するために、手動でコードを実行する必要があります。まだ行っていない場合は、変更内容に対するテストケースを作成することをお勧めします。前述の通り、コードがコメントアウトされているか、存在しない場合、このテストは失敗するはずです。

テストケースをテストスイートに追加すると、他のテストと一緒に実行できるようになります。次のステップは、テストスイートを実行することです。

テストの実行およびカバレッジ¶

BeeWareは、テストプロセスの管理にtoxを使用し、独自のテストスイートにはpytestを使用しています。

デフォルトの tox コマンドには、以下の実行が含まれます：

プレコミットフック
towncrier リリースノートの確認
ドキュメントのリンティング
利用可能なPythonバージョン向けのテストスイート
コードカバレッジレポート

これは、プルリクエストを送信した際にCIによって実行される処理の要約です。

テストスイート全体を実行するには、次のコマンドを実行してください：

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

テストスイート全体の実行には時間がかかる場合があります。tox を並列実行するか、tox p（または tox run-parallel）を実行することで、実行速度を大幅に上げることができます。テストスイートを並列実行すると、実行中の進捗状況に関するフィードバックは少なくなりますが、テスト実行終了時には検出された問題の概要が表示されます。テストが実行されたことを示す何らかの出力が表示されるはずです。 SKIPPED テストが表示されることはありますが、FAIL や ERROR といったテスト結果が表示されることは決してありません。私たちは、パッチをマージする前に毎回、完全なテストスイートを実行しています。その過程で問題が発見された場合、そのパッチはマージされません。もしテストエラーや失敗が見つかった場合は、テスト環境に何か異常があるか、あるいは私たちがこれまで遭遇したことのないエッジケースを発見したかのどちらかです。いずれにせよ、ぜひお知らせください！

テストが成功したことに加え、100%のテストカバレッジが報告されるはずです。

テストのバリエーションを実行する¶

複数のPythonバージョンでテストを実行する¶

デフォルトでは、多くのtoxコマンドは、BeeWareがサポートする各Pythonバージョンに対して1回ずつ、テストスイートを複数回実行しようとします。ただし、これを行うには、各Pythonバージョンがマシンにインストールされており、toxのPython 検出プロセスから利用可能である必要があります。一般的に、PATH経由でPythonのバージョンが利用可能であれば、toxはそのバージョンを見つけて使用できるはずです。

テストスイートのみを実行する¶

新機能の開発で迅速に反復開発を行っている場合、テストスイート全体を実行する必要はなく、ユニットテストのみを実行すれば十分です。これを行うには、次のコマンドを実行します：

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

テストの一部を実行する¶

デフォルトでは、tox はユニットテストスイート内のすべてのテストを実行します。新しいテストを開発している際、そのテストを「そのテストだけ」実行したい場合があるかもしれません。その場合は、pytest の引数として [任意の (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run) 指定子]tox を渡すことで実現できます。これらのテストパスは briefcase ディレクトリを基準としています。たとえば、単一のファイル内のテストのみを実行するには、次のように実行します：

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

テストスイートの一部を実行しても、カバレッジレポートは表示されますが、カバレッジの結果には、実行した特定のテストによって実行されたコード行のみが報告されます。

特定のPythonバージョンに対してテストスイートを実行する¶

デフォルトでは、tox -e py は、お使いのマシン上で python として解決されるインタープリタを使用して実行されます。複数の Python バージョンがインストールされており、インストール済みのバージョンの中から特定の Python バージョンでテストを実行したい場合は、使用する Python バージョンを指定することができます。たとえば、Python 3.10 でテストスイートを実行するには、次のように実行します：

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

コマンドラインに -- とテスト仕様を追加することで、テストのサブセットを実行できます。

カバレッジを計測せずにテストスイートを実行する（高速）¶

デフォルトでは、tox は pytest スイートをシングルスレッドモードで実行します。テストスイートを並列で実行することで、実行速度を向上させることができます。このモードでは、生成されたプロセス内でのカバレッジの取得が複雑なため、カバレッジファイルは生成されません。単一の Python バージョンを「fast」モードで実行するには、次のように実行してください：

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

コマンドラインに -- とテスト仕様を追加することで、テストのサブセットを実行できます。また、テストターゲットにバージョンを追加することで、特定の Python バージョンを使用できます（例：Python py310-fast で高速に実行するには 3.10 を指定します）。

コードカバレッジ¶

BeeWareは、コードベースにおいて100%のテストカバレッジを維持しています。プロジェクトにコードを追加または変更する際は、変更箇所を確実にテストできるよう、テストコードを追加する必要があります。

ただし、BeeWareは複数のプラットフォームおよび複数のPythonバージョンを対象としているため、単一のプラットフォームやPythonバージョンでは完全なカバレッジを検証することはできません。この問題に対処するため、tool.coverage.coverage_conditional_plugin.rules の pyproject.toml セクションにはいくつかの条件付きカバレッジルールが定義されています（例えば、no-cover-if-is-windows を使用すると、Windows でテストスイートを実行した際に実行されないコードブロックをマークできます）。これらのルールは、特定のプラットフォームや Python バージョンでのみカバレッジが確保されているコードのセクションを特定するために使用されます。

なお、Pythonのバージョンが異なる場合、カバレッジレポートには若干の不整合が生じることがあります。例えば、カバレッジファイルをあるバージョンのPythonで生成したものの、レポート作成を別のバージョンで行った場合、レポートには未検出の分岐に関する誤検知が含まれる可能性があります。このため、カバレッジレポートを作成する際は、常にカバレッジファイルの生成に使用したPythonのバージョンの中で最も古いバージョンを使用するようにしてください。

保険適用範囲の結果の理解¶

カバレッジテストの出力の最後には、収集されたカバレッジデータのレポートが表示されるはずです：

名称    残高   未決済   ブランチ・ブランチ・パート   カバー   欠落
 ---------------------------------------------------
 合計    7540 0   1040 0  100.0%

これは、テストスイートがコード内のあらゆる分岐パスを網羅して実行したことを示しています。これはバグが一切ないことを100％保証するものではありませんが、コードベース内のすべての行が実行されていることを意味します。

コードベースに変更を加えると、カバレッジに穴が生じる可能性があります。その場合、カバレッジレポートには、どの行が実行されていないかが表示されます。例えば、some/interesting_file.pyに変更を加えて新しいロジックを追加したとします。その場合のカバレッジレポートは、次のようなものになるでしょう：

名前 ステートメント数   ミス   分岐   BrPart  カバレッジ   欠落
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 合計 7540 1   1726 0  99.9%

これは、170行目、302行目から307行目、および320行目から335行目への分岐が、テストスイートによって実行されていないことを示しています。このカバレッジを回復するには、新しいテストを追加するか、既存のテストを修正する必要があります。

ホストプラットフォームおよびPythonバージョンの対応状況レポート¶

お使いのプラットフォームおよびPythonのバージョンに対応したカバレッジレポートを生成できます。たとえば、Python 3.10 でテストスイートを実行し、カバレッジレポートを生成するには、次のように実行します：

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

ホストプラットフォームの対応状況レポート¶

tox でサポートされているすべての Python バージョンが利用可能な場合、ホストプラットフォームのカバレッジは次のコマンドを実行することで報告できます：

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

HTML形式でのカバレッジレポート¶

カバレッジ環境名の末尾に -html を付けることで、HTML 形式のカバレッジレポートを生成できます。例えば：

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

テストを書くことだけが目的ではありません！¶

私たちはすべてのコードを確実にテストしていますが、その任務は単にそのレベルのテストを維持することだけではありません。その任務の一部は、開発を進めながらコードを監査することにもあります。コンクリート製の救命胴衣のために包括的なテストスイートを作成することは可能でしょう……しかし、コンクリート製の救命胴衣は、本来の目的を果たすには依然として役に立たないのです！

テストを開発する際は、コアモジュールが内部的に一貫性を持っているかどうかも確認するようにしてください。もし、メソッド名に内部的な一貫性がない場合（例：あるモジュールではon_selectという名前なのに、別のモジュールではon_selectedという名前になっているなど）、あるいはデータの扱いに一貫性がない場合を見つけたら、それをマークし、チケットを立てて私たちに知らせてください。あるいは、どう修正すべきか確信がある場合は、見つけた問題を修正するプルリクエストを作成してください。

問題の修正にドキュメントの変更が必要な場合：

ドキュメントを作成する

BeeWareのドキュメントに変更を加える前に、既存のドキュメントをビルドできることを確認しておくことが有用です。

Python 3.13 インタプリタがインストールされ、パス上で利用可能であることが必須です（つまり、python3.13 は Python 3.13 インタプリタを起動する必要があります）。

BeeWare はドキュメント作成に tox を使用します。以下の tox コマンドは、プロジェクトのルートディレクトリにある tox.ini ファイルと同じ場所から実行する必要があります。

ライブドキュメントプレビュー¶

ドキュメントの迅速な編集をサポートするため、BeeWareには「ライブプレビュー」モードが備わっています。

ライブプレビューは警告付きでビルドされます！

ライブサーブはドキュメント更新の反復作業に利用可能です。更新作業中にマークアップの問題が発生する可能性があります。WARNINGで囲まれた問題は標準ビルドを失敗させますが、ライブサーブはコンソール出力に警告を表示しつつビルドを継続するよう設定されています。これにより、ライブプレビューを再起動せずに反復作業が可能です。

WARNING は ERROR とは異なります。ERROR とみなされる問題が発生した場合、ライブサーバーは失敗し、再起動が必要となります。WARNING の問題が解決されるまで、サーバーは再起動しません。

ライブサーバーを起動するには：

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

これにより、ドキュメントがビルドされ、ドキュメントを提供するWebサーバーが起動され、ドキュメントソースの変更をファイルシステムで監視します。

サーバーが起動すると、コンソール出力に以下のような内容が表示されます：

INFO    -  [11:18:51] http://127.0.0.1:8000/ で配信中

ブラウザを開き、提供されたURLにアクセスしてください。これでドキュメントの反復作業を開始できます。変更が検出されると、ドキュメントが再構築され、変更されたページを表示しているブラウザは自動的に更新されます。

docs-liveは最初のステップです

docs-liveを実行してライブサーバーと連携するのは初期段階の反復作業を目的としています。プルリクエストを送信する前には必ずローカルビルドを実行してください。

ローカルビルド¶

反復処理が完了したら、ドキュメントのローカルビルドを実行する必要があります。このビルドプロセスは、マークアップに問題がある場合に失敗するよう設計されています。これにより、ライブサーバーでは見逃していた可能性のある問題を検出できます。

ローカルビルドの生成¶

ローカルビルドを生成するには：

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

このビルドの出力は、プロジェクトのルートディレクトリにある _build ディレクトリに配置されます。

ローカル翻訳ビルドの生成¶

BeeWare'sのドキュメントは複数言語に翻訳されています。英語版ドキュメントの更新は、他の言語版ビルドに問題を引き起こす可能性があります。プルリクエストを送信する前に、すべてのビルドが正常に動作することを確認することが重要です。

利用可能なすべての翻訳のビルドを生成するには：

macOSLinuxWindows

(動詞) $ tox -e docs-all

(動詞) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

各言語ビルドの出力は、関連付けられた_build/html/<languagecode>ディレクトリに配置されます。ここで<languagecode>は、特定の言語に関連付けられた2文字または5文字の言語コードです（例：フランス語はfr、イタリア語はitなど）。

単一のビルドに問題が見つかった場合、tox -e docs-<languagecode> を実行することでその個別のビルドを単独で実行できます。例えば、フランス語のドキュメントのみをビルドするには、以下を実行します：

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

単一言語ビルドの出力は _build ディレクトリに配置されます。

ドキュメントのリンティング¶

ビルドプロセスではMarkdownの問題を検出しますが、BeeWareはスタイルや書式に関する追加チェック（いわゆる「リンティング」）を実行します。リンティングチェックを実行するには：

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

これにより、ドキュメントに以下の内容が含まれていないことが検証されます：

無効なハイパーリンク
誤字

単語の正しい綴りが誤りとして検出された場合、その単語をdocs/spelling_wordlist内のリストに追加してください。これにより、その単語がスペルチェッカーの辞書に追加されます。このリストに追加する際は、以下の点に注意してください：

米国式スペルを優先しますが、プログラミング特有の慣用表現（例：「apps」）や名詞の動詞化（例：「scrollable」）については一部例外を認めます。
製品名への言及は、製品が推奨する大文字表記を使用してください（例：「macOS」、「GTK」、「pytest」、「Pygame」、「PyScript」）。
ある用語が「暗号として」使用されている場合、辞書に追加するのではなく、リテラル（like this）として引用すべきである。

ドキュメントを作成する

BeeWareへのドキュメント貢献を書くための手順は以下の通りです。

既存のドキュメントの更新¶

既存のドキュメントを編集する場合は、/docs/enディレクトリ内のファイルを特定する必要があります。ファイル構造はページ構造に準拠しているため、ドキュメントURLからファイルを特定できます。

新しいドキュメントの追加¶

新しいドキュメントを追加する場合は、さらにいくつかの手順が必要です。

docs/enディレクトリ内の適切な場所にドキュメントを作成する必要があります。説明のため、ファイル名new_doc.mdの新しいドキュメントを追加すると仮定します。

次に、新しいファイルを含めるためにdocs/en/SUMMARY.mdファイルを更新する必要があります。SUMMARY.mdは基本的にdocs/enディレクトリ構造を反映するように構成されていますが、より重要なのは左サイドバーの構造を直接決定する点です。new_doc.mdを含めたいセクションを見つけたら、ワイルドカードパスが記載されている場合はSUMMARY.md内で何も変更する必要はありません。例：

- ./ディレクトリへのパス/*

new_doc.mdを含めようとするセクションが個別のMarkdownリンクのリストである場合、明示的なリンクを追加する必要があります。例：

- [新しいドキュメント](new_doc.md)

ドキュメントの作成¶

目的のファイルをエディタで開いて、書き始めることができます。

BeeWareのドキュメント作成に関するガイドラインをまとめたドキュメントスタイルガイドを用意しています。

投稿の準備が整いましたら：

変更メモを追加する

多くのBeeWareツールでは、各リリースのリリースノート作成を支援するためにtowncrierを使用しています。該当するツールのいずれかにプルリクエストを送信する際には、変更ノートを含める必要があります。この変更ノートは、行われた変更を説明するリリースノートの項目となります。

すべてのプルリクエストには、changes/ディレクトリ内に少なくとも1つのファイルを含める必要があります。このファイルには、プルリクエストで実装された変更内容の簡潔な説明を記載してください。変更ノートはMarkdown形式で、<id>.<fragment type>.mdという形式の名前を持つファイルに記述します。提案する変更が既存の課題番号を持つバグ修正または機能実装である場合、IDはそのチケット番号となります。変更に対応するイシューが存在しない場合、プルリクエスト番号をIDとして使用できます。このプルリクエスト番号はプルリクエストをプッシュするまで確認できません。そのため、最初のCIパスではtowncrierチェックが失敗します。変更ノートを追加し、プルリクエストを更新してプッシュすると、CIは通過するはずです。

断片タイプは5種類あります：

feature: このプルリクエストは、以前には不可能だった新しい動作や機能を追加します（例：新しいパッケージング形式のサポート追加、または既存のパッケージング形式における新機能の追加）。
bugfix: このPRは既存の実装におけるバグを修正します；
PRはドキュメントの大幅な改善です；
removal; このPRはBeeWare APIにおける後方互換性のない変更を表しています; または
misc; リリースノートで発表する必要のない、軽微な変更または管理上の変更（例：誤字の修正、言語の軽微な明確化、依存関係のバージョン更新など）。

この変更ノートの説明は、ユーザー視点からの変更内容に関する高レベルの「マーケティング」要約であるべきであり、深い技術的説明や実装の詳細ではない。これはコミットメッセージとは異なる。コミットメッセージは、将来の開発者が変更の理由を追跡できるように、何が行われたかを記述するものである。一方、変更ノートは内部知識を持たない可能性のあるユーザーのために記述される説明である。

たとえば、プロジェクトの命名に関するバグを修正した場合、コミットメッセージは次のように記述できます：

プロジェクト名が数字で始まることを禁止するため、より強力な正規表現チェックを適用する。

対応する変更ノートは次のような内容になります：

プロジェクト名は数字で始まることはできなくなりました。

一部のプルリクエストでは、複数の機能導入やバグ修正、あるいは複数の後方互換性のない変更が行われる場合があります。その場合、PRには複数の変更ノートファイルが存在する可能性があります。同じIDを持つ2つのフラグメントタイプを関連付ける必要がある場合は、数値のサフィックスを追加できます。例えば、PR 789がチケット123で説明される機能を追加し、チケット234で説明されるバグを修正し、さらに2つの後方互換性のない変更を行った場合、4つの変更ノートファイルが存在することになります：

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

towncrierおよびフラグメントタイプの詳細については、ニュースフラグメントを参照してください。また、changesリポジトリのBeeWareディレクトリ内に既存のニュースフラグメントの例があります。このフォルダが空の場合、BeeWare が最近新バージョンをリリースしたためと考えられます。変更履歴ファイルは削除され、各リリースごとにリリースノートの更新に統合されます。必要なコメントのスタイルを確認するにはそのファイルを参照してください。変更ノートのフォーマット方法については、最近マージされたプルリクエストを参照してください。

プルリクエストを送信する

すべての変更をコミットしたところで、プルリクエストを送信する準備が整いました。スムーズなレビュープロセスを確保するため、いくつかの手順を踏む必要があります。

プレコミットとの連携¶

変更をコミットする際、pre-commitが自動的に実行されます。コミットに問題が検出された場合、コミットは失敗します。可能な限り、pre-commitは検出した問題を修正するために必要な変更を加えます。以下の例では、ruffチェックによってコードのフォーマット問題が検出されました：

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

この場合、ruffによって問題が自動的に修正されました。したがって、プリコミットチェックの結果変更されたファイルを再度追加し、変更を再コミットできます。ただし、一部のチェックでは手動での修正が必要になる場合があります。それらの変更を加えた後は、変更されたファイルを再度追加し、再コミットしてください。

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

すべてが完了すると、コミットが確定したことを示すメッセージが表示され、git log でそのコミットが最新の追加として確認できます。これで GitHub へのプッシュ準備が整いました。

変更を GitHub にプッシュし、プルリクエストを作成してください¶

GitHubに初めてプッシュすると、新しいプルリクエストを作成するためのGitHubページに直接移動するURLが提供されます。そのURLにアクセスしてプルリクエストを作成してください。

以下は、URLが強調表示された状態でpushに表示される内容の例です。

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

現在のブランチを以前にGitHubにプッシュしたことがある場合、URLは再度送信されません。ただし、PR作成URLにアクセスする他の方法があります：

アップストリームリポジトリに移動し、「プルリクエスト」をクリックした後、「新しいプルリクエスト」を選択し、プルリクエストを送信したいブランチを選択してください。
最近プッシュした場合は、アップストリームリポジトリに移動し、ファイル一覧の上部に表示される「最近プッシュがあった」ことを示すバナーを見つけ、「比較してプルリクエスト」ボタンをクリックしてください。
GitHub CLI gh pr create コマンドを使用し、プロンプトに従って入力してください。
GitHub CLI gh pr create --web コマンドを使用して、PR作成ページにウェブブラウザを開きます。

これらのいずれかのオプションを選択することで、新しいプルリクエストを作成できます。

GitHub CLI: gh

GitHubはGitHub CLIを提供しており、これによりターミナルからghコマンドを通じてGitHubの多くの機能にアクセスできます。すべての機能についてはGitHub CLIドキュメントを参照してください。

プルリクエストの内容¶

プルリクエストのタイトルは、情報豊富で明確かつ簡潔である必要があります。可能な限り短く保つよう心がけましょう。ただし、必要に応じて長いタイトルも許容されます。優れたPRタイトルは、文脈を知らない人でも、そのPRでどのバグ修正や機能が実装されているかを十分に理解できるものでなければなりません。

プルリクエストの説明文は、PRの変更内容を明確に反映しなければなりません。文脈を知らない人が説明文を読んだだけで、変更の理由を比較的完全に理解できる必要があります。冗談、慣用句、口語表現、および大文字のみの使用や過剰な句読点といった不要な書式設定は避けてください。これはPRで何が起こっているかを率直に説明するものであり、こうした要素を排除することで説明文の理解しやすさが向上します。

PRに既に含まれていない再現ケースやテスト手順がある場合は、それらを説明しPRに含める必要があります。説明には、それらの実行方法と、望ましい結果を再現するための手順を含めるべきです。

プルリクエストが issue #1234 を解決する場合、プルリクエストの説明に Fixes #1234 というテキストを含める必要があります。これにより、プルリクエストがマージされると自動的に issue が閉じられます。他のディスカッション、issue、プルリクエストも同様の #1234 構文で参照できます。異なるリポジトリの issue を参照するには、番号の前に - を付加します。例えば python/cpython#1234 は CPython リポジトリの issue 1234 を指します。

継続的インテグレーション¶

継続的インテグレーション（CI）とは、プルリクエストに対して自動化されたチェックを実行するプロセスです。これには、コードが正しくフォーマットされていることを確認するといった単純なチェックが含まれますが、テストスイートの実行やドキュメントのビルドも含まれます。

CIの失敗を引き起こす変更は数多く存在します。大まかに言えば、CIを通過していないプルリクエストはレビューしません。プルリクエストを作成してCIが失敗した場合、通過するまでレビューを開始しません。変更が失敗の原因となった場合、その理由を調査し問題を解決するのはあなたの責任です。

CIが失敗した場合、失敗したリンクはPRページの下部、「一部のチェックが成功しませんでした」という見出しの下に表示されます。失敗したチェックの一覧が表示され、合格したチェックがある場合でも、この失敗チェックは全チェックリストの最上部に表示されます。失敗リンクをクリックするとログが表示されます。ログには失敗の原因を特定するために必要な情報がほぼ全て記載されています。ログを読み込み、失敗の原因を特定した上で、必要な対応を行ってください。

時折、CIチェックが変更内容とは無関係な理由で失敗することがあります。これはCIチェックを実行するマシン側の問題、あるいはCIチェック自体が不安定であることが原因です。失敗を確認し、それが変更内容と無関係であると確信できる場合は、その旨をプルリクエストにコメントとして追加してください。調査いたします。

新しいCI実行をトリガーするには、ブランチに新しい変更をプッシュする必要があります。

CIを通過させるのに助けが必要な状況に陥った場合は、プルリクエストにコメントを残してその旨をお知らせください。できる限りのサポートをいたします。

pre-commit および towncrier チェック

pre-commit または towncrier のいずれかのチェックが失敗した場合、残りのほとんどの CI チェックの実行がブロックされます。チェックの全セットを実行するには、該当する問題を解決する必要があります。

CIリソースには限りがあります。ブランチにプッシュするたびにCIが開始されることを理解することが重要です。複数の変更を加える場合は、ローカルで変更を加え、まとめてプッシュすることをお勧めします。CIはバッチ内の最新コミットのみを実行するため、CIシステムへの負荷を最小限に抑えられます。

PRの提出プロセスは、CIを通過するか、または通過しない理由を説明できるまで完了しません。

問題の修正¶

問題修正の貢献¶

前提条件¶

開発環境を設定する¶

BeeWare リポジトリをクローンする¶

上流リポジトリを設定する¶

仮想環境を作成する¶

インストール BeeWare¶

コミット前の検証を有効にする¶

コード内のバグ¶

ドキュメントのバグ¶

問題を更新する¶

テスト駆動開発¶

コードを実行する¶

テストの実行 およびカバレッジ¶

テストのバリエーションを実行する¶

複数のPythonバージョンでテストを実行する¶

テストスイートのみを実行する¶

テストの一部を実行する¶

特定のPythonバージョンに対してテストスイートを実行する¶

カバレッジを計測せずにテストスイートを実行する（高速）¶

コードカバレッジ¶

保険適用範囲の結果の理解¶

ホストプラットフォームおよびPythonバージョンの対応状況レポート¶

ホストプラットフォームの対応状況レポート¶

HTML形式でのカバレッジレポート¶

テストを書くことだけが目的ではありません！¶

ライブドキュメントプレビュー¶

ローカルビルド¶

ローカルビルドの生成¶

ローカル翻訳ビルドの生成¶

ドキュメントのリンティング¶

既存のドキュメントの更新¶

新しいドキュメントの追加¶

ドキュメントの作成¶

プレコミットとの連携¶

変更を GitHub にプッシュし、プルリクエストを作成してください¶

プルリクエストの内容¶

継続的インテグレーション¶

テストの実行およびカバレッジ¶