新機能の実装¶

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

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

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

新機能の提供¶

開発環境を構築する

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

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

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

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

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

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

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

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

新機能を実装する

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