基本¶

Blackプロジェクトへのコントリビューションの概要。

技術的な詳細¶

最新のPythonバージョンでの開発が推奨されます。任意のオペレーティングシステムを使用できます。

例えば、お好みの仮想環境内に開発用依存関係をインストールします。

$ python3 -m venv .venv
$ source .venv/bin/activate # activation for linux and mac
$ .venv\Scripts\activate # activation for windows

(.venv)$ pip install -r test_requirements.txt
(.venv)$ pip install -e ".[d]"
(.venv)$ pre-commit install

プルリクエストを送信する前に、Blackリポジトリのルートから以下のコマンドを実行して、lintとテストを実行してください。

# Linting
(.venv)$ pre-commit run -a

# Unit tests
(.venv)$ tox -e py

# Optional Fuzz testing
(.venv)$ tox -e fuzz

# Format Black itself
(.venv)$ tox -e run_self

開発¶

テストの実行のさらなる例

# Run all of the above mentioned, in parallel
(.venv)$ tox --parallel=auto

# Run tests on a specific python version
(.venv)$ tox -e py39

# pass arguments to pytest
(.venv)$ tox -e py -- --no-cov

# print full tree diff, see documentation below
(.venv)$ tox -e py -- --print-full-tree

# disable diff printing, see documentation below
(.venv)$ tox -e py -- --print-tree-diff=False

テスト¶

Blackスタイルのあらゆる側面をテストする必要があります。通常、テストはtests/data/casesディレクトリにファイルとして作成する必要があります。これらのファイルは最大3つの部分で構成されます。

# flags: で始まる行、それに続くコマンドラインオプションのセット。例えば、行が# flags: --preview --skip-magic-trailing-commaの場合、テストケースはプレビューモードがオンでマジック末尾のカンマがオフの状態で実行されます。--minimum-version=フラグを除いて、受け入れられるオプションはほとんどBlack自体のオプションのサブセットです。--minimum-version=フラグは、新しいバージョンのPythonでのみ機能する構文機能をテストする場合に使用します。このフラグにより、古いバージョンでASTの検証を試みず、機能が使用されている場合にPythonバージョンを正しく自動検出することをテストします。受け入れられる正確なフラグについては、tests/util.pyのget_flags_parser関数を参照してください。この行を省略した場合、デフォルトのオプションが使用されます。
フォーマッターの入力として使用されるPythonコードのブロック。
# output行、それに続く前のブロックで実行されたBlackの出力。これを省略した場合、テストはBlackが入力コードを変更しないことをアサートします。

Blackには、tests/data/内のテストファイルを、入力部分と出力部分に分割し、# outputの行で区切られた2つのpytestコマンドラインオプションがあります。これらはtoxを介してpytestに渡すか、toxを使用していない場合は直接pytestに渡すことができます。

`--print-full-tree`¶

テストが失敗した場合、入力の処理後の具体的な構文木（CST）（「実際の」）と、出力の解析後の結果のツリー（「期待される」）を完全に表示します。同じCSTでも出力は異なる場合があります。以前はデフォルトでしたが、現在はFalseがデフォルトです。

`--print-tree-diff`¶

テストが失敗した場合、上記のようにツリーの差分を表示します。これがデフォルトです。オフにするには--print-tree-diff=Falseを渡します。

ニュース/変更ログの要件¶

Blackには、CHANGES.mdでPRに対応するエントリをチェックするCIがあります。このPRに変更ログのエントリが必要ないと感じる場合は、コメントでそれを述べてください。メンテナがskip newsラベルを追加してCIを通過させることができます。それ以外の場合は、次の形式の行があることを確認してください。

- `Black` is now more awesome (#X)

Xはイシュー番号ではなく、PR番号であることに注意してください！Xを調べるには、Next PR Numberを使用してください。これは完璧ではありませんが、リリース担当者が各リリースのCHANGES.mdに追加するものを後から調べる必要がなくなるため、リリースのオーバーヘッドを大幅に削減します。

スタイルの変更¶

変更が公開されているコードスタイルに影響を与える場合、その変更を反映するようにドキュメント（Blackコードスタイル）を変更してください。フォーマットの意図しないバグを修正するパッチは、別途言及する必要はありません。変更が--previewフラグで実装されている場合は、将来のスタイルドキュメントに変更を含めて、「プレビューの変更」という専用のヘッダーの下に変更ログのエントリを書いてください。

ドキュメントのテスト¶

ドキュメントに変更を加えた場合、ローカルでもビルドできるかどうかをテストできます。

(.venv)$ pip install -r docs/requirements.txt
(.venv)$ pip install -e .[d]
(.venv)$ sphinx-build -a -b html -W docs/ docs/_build/

衛生管理¶

バグを修正する場合は、テストを追加します。最初に実行して失敗することを確認してから、バグを修正し、再度実行して実際に修正されていることを確認します。

新しい機能を追加する場合は、テストを追加します。実際、常にテストを追加します。しかし、大きな機能を追加する前に、まずイシューを開いてアイデアについて最初に話し合うようにしてください。

最後に¶

プロジェクトの改善に関心を持っていただき、ありがとうございます！多くの人が見ているだけで行動を起こすことを決める中で、あなたは行動を起こしています。

基本¶