新機能の実装¶

提案プロセスが終了したら、新機能の完全な設計が整っているはずです。つまり、いよいよ実装を始める時が来たということです！

機能がプラットフォーム固有の実装を必要とする場合、提案プロセスにおいてそのアイデアが全プラットフォームで実装可能であることが検証されている必要があります。ただし、新規機能を初めて実装する者として、全プラットフォーム向けの実装責任を負う必要はありません。少なくとも1つのプラットフォームに対しては、テストを含む完全な実装を提供する必要があります。その他のプラットフォームについては、「スタブ」実装を提供する必要があります。これは、最低限のインターフェース定義を提供するものの、そのプラットフォームでは動作が実装されていないことを示すNotImplementedErrorをスローするか、ログメッセージを出力する実装です。

新機能の実装において重要なのは、その機能が完全に文書化されていることを保証することです。最低限、APIドキュメントが存在するのを確認することですが、ハウツーやトピックガイドの追加が必要になる場合もあります。

新機能の提供¶

開発環境を構築する

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

スコープクリープを避ける

スコープクリープとは、単一の貢献によって解決される問題や実装される機能のリストが、作業開始時に想定していた範囲を大幅に超えて膨張する現象を指す。単純な問題から着手し、密接に関連する問題を発見してその修正も追加し、さらに第三の問題が…気がつくと、5件の問題を解決し3つの新機能を追加するプルリクエストが完成している。そこには数十ものファイルが含まれているのだ。

スコープクリープは誰にでも起こり得る。経験豊富な開発者にとってはおなじみの概念であり、誰もが何度も経験し、それに伴うあらゆる問題に直面してきた。

スコープクリープを避けるべき非常に現実的な理由があります。貢献が大きくなるほど、扱いが難しくなります。エッジケースや潜在的な問題を特定するのが困難になり、貢献の全体的な品質が低下する可能性があります。また、レビュアーが複数の、おそらく関連性のないコンテキストを扱う必要がある場合、レビュー作業もより困難になります。貢献が大きくなるほどレビューコメントも増え、貢献者として複数のレビュースレッドを追うのが難しくなる可能性があります。GitHubの操作体験さえも損なわれます——プルリクエストのサイズが大きくなるにつれてGitHubのUIは遅くなり、GitHubインターフェースを通じてファイルをナビゲートしたりレビューコメントを残そうとしたりすることが次第に困難になるのです。

貢献内容に、元の提案やバグ報告に明示的に含まれていない要素を追加する理由を見つけた場合は、スコープクリープに陥っていないか検討すべきです。別々に実装可能な2つの独立した機能はありませんか？既知の制限やバグを抱えた状態で機能を実装し、後続のプルリクエストでそのバグを修正することは可能ですか？バグ修正の一部は他の部分と独立していませんか？変更の一部を省略しても元の貢献内容が変わらない場合、おそらく省略すべきです。

ソフトウェア開発は常に段階的な改善のプロセスです。個々の貢献はマージの結果としてコードベースをより良い状態にすべきですが、バグや機能の一部を将来の改善課題として残すことは全く問題ありません。そのためにはプルリクエストを独立してレビュー可能な複数の部分に分割したり、誰かが調査・解決できるよう問題を記録したりすることが考えられます。

各投稿の範囲を限定することは、関係者全員、あなた自身も含めて有益です。査読者も、そしてあなた自身も、そのことを高く評価するでしょう。

新機能を実装する

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

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 にプッシュし、プルリクエストを作成してください¶

プルリクエストの内容¶

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

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