問題の修正¶

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

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

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

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

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

問題修正の貢献¶

開発環境を構築する

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

前提条件¶

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

macOSLinuxWindows

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

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

$ python3 --version

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

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

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

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

$ python3 --version

複数の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/<your username>/beeware.git

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

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

$ git clone https://github.com/<your username>/beeware.git

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

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

C:\...>git clone https://github.com/<your username>/beeware.git

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

仮想環境を作成する¶

仮想環境を設定し、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ブランチから行った場合、そのクリーンなバージョンはもはや利用できません。

Instead, you should make your changes on a feature branch. A feature branch has a simple name to identify the change that you've made. For example, if you're fixing a bug that causes build issues on Windows 11, you might create a feature branch fix-win11-build. If your bug relates to a specific issue that has been reported, it's also common to reference that issue number in the branch name (e.g., 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アップデートで問題が解決された可能性がある場合など）、その推測もコメントの一部として含めてください。

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

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

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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
合計 7540 0 1040 0 100.0%

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

名称 ステートメント ミス ブランチ ブランチ部分 カバー 欠落
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
合計 7540 1 1726 0 99.9%

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

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

/// details-abstract | ドキュメントを作成する

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



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

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

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

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

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

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

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

///

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



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(venv) $ tox -e docs-live

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

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

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

INFO    -  [11:18:51] Serving on 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

(venv) $ tox -e docs-all

(venv) $ 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内で何も変更する必要はありません。例：

- ./path/to/directory/*

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

- [My new document](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を通過するか、または通過しない理由を説明できるまで完了しません。