コントリビューティング¶

貢献は大歓迎であり、感謝されます。どんな小さな助けでも役に立つので、ためらわないでください！

機能リクエストとフィードバック¶

pytest が好きですか？ Twitter やブログ投稿で愛を共有してください！

あなたの提案や提案についても聞きたいです。気軽に問題として提出してくださいと：

それらがどのように機能するかを詳細に説明してください。
範囲をできるだけ狭く保ちます。これにより、実装が容易になります。

バグを報告する¶

pytest のバグを issue tracker に報告してください。

バグを報告する場合は、次の情報を含めてください：

オペレーティングシステムの名前とバージョン。
トラブルシューティングに役立つ可能性のあるローカル設定の詳細、特に Python インタープリターのバージョン、インストールされているライブラリ、および pytest のバージョン。
バグを再現するための詳細な手順。

現在失敗しているが合格するはずのデモンストレーションテスト（xfail）を書くことができる場合、それは非常に有用なコミットです。バグ自体を修正できなくても。

バグを修正する¶

GitHub issues for bugs を確認してください。新しい貢献者に優しい "good first issue" issues も参照してください。

Talk して、特定のバグをどのように修正できるかを開発者に確認してください。特定の問題に取り組むことを示すために、その問題にその旨のコメントを追加してください。

お気に入りのプラグインの issue tracker も忘れずにチェックしてください！

機能を実装する¶

GitHub issues for enhancements を確認してください。

Talk して、特定の機能をどのように実装できるかを開発者に確認してください。

ドキュメントを書く¶

Pytest は常により多くのドキュメントを必要としています。具体的に何が必要ですか？

より補完的なドキュメント。何か不明な点がありましたか？
ドキュメントの翻訳。現在、英語のみです。
Docstrings。いくらあっても多すぎることはありません。
ブログ投稿、記事など -- すべて非常に感謝されます。

ローカルコピーを使用せずに、GitHub の Web インターフェースでドキュメントファイルを直接編集することもできます。これは小さな修正に便利です。

注釈

次のコマンドを使用してローカルでドキュメントをビルドします：

$ tox -e docs

ビルドされたドキュメントは doc/en/_build/html にあるはずです。ここで 'en' はドキュメントの言語を指します。

Pytest には API リファレンスがあり、その大部分はドキュメント化された項目の docstring から自動的に生成されます。 Pytest は Sphinx docstring format を使用します。例えば：

def my_function(arg: ArgType) -> Foo:
    """Do important stuff.

    More detailed info here, in separate paragraphs from the subject line.
    Use proper sentences -- start sentences with capital letters and end
    with periods.

    Can include annotated documentation:

    :param short_arg: An argument which determines stuff.
    :param long_arg:
        A long explanation which spans multiple lines, overflows
        like this.
    :returns: The result.
    :raises ValueError:
        Detailed information when this can happen.

    .. versionadded:: 6.0

    Including types into the annotations above is not necessary when
    type-hinting is being used (as in this example).
    """

pytest-dev へのプラグインの提出¶

pytest コア、サポートコード、および一部のプラグインの開発は、pytest-dev 組織の下にあるリポジトリで行われます：

GitHub 上の pytest-dev

すべての pytest-dev コントリビューターチームのメンバーは、含まれるすべてのリポジトリに書き込みアクセス権を持っています。 pytest コアおよびプラグインは、一般的にそれぞれのリポジトリへのプルリクエストを使用して開発されます。

pytest-dev 組織の目的は：

人気のある pytest プラグインの中央場所を持つこと
メンテナンスの責任を共有すること（メンテナーがプラグインのメンテナンスを希望しなくなった場合）

pytest-dev メーリングリストに登録し、次の要件を満たす既存の pytest プラグインリポジトリを指すメールを書いてプラグインを提出できます：

pytest- プレフィックス付きの名前、バージョン番号、著者、短い説明と長い説明を含むパッケージングメタデータを持つ PyPI プレゼンス。
tox を使用してテストを実行するための tox configuration。
プラグインの使用方法と実行されるプラットフォームを説明する README。
ライセンス情報を含む LICENSE ファイル、およびそのパッケージングメタデータに一致する情報。
バグ報告と機能強化リクエストのための issue tracker。
changelog。

強く反対するコントリビューターがいない場合、2 人が同意すれば、リポジトリを pytest-dev 組織に転送できます。

リポジトリ転送が通常どのように進行するかの概要を次に示します（joedoe/pytest-xyz という名前のリポジトリを例として使用）：

joedoe はリポジトリの所有権を pytest-dev 管理者 calvin に転送します。
calvin は pytest-xyz-admin および pytest-xyz-developers チームを作成し、joedoe を メンテナー として両方に招待します。
calvin はリポジトリを pytest-dev に転送し、チームアクセスを構成します：
- pytest-xyz-admin 管理者 アクセス；
- pytest-xyz-developers 書き込み アクセス；

pytest-dev/Contributors チームはすべてのプロジェクトに書き込みアクセス権を持っており、すべてのプロジェクト管理者が含まれています。各プラグインには、PyPI にリリースする権利を持つ少なくとも 3 人の人がいることをお勧めします。

リポジトリの所有者は、数か月間の連絡試行の後に誰かが応答しなくなるというまれなケースを除いて、pytest-dev 管理者がリポジトリのリリースを行ったり、所有権を取得したりすることは決してないことを安心できます。述べたように、目的はメンテナンスを共有し、「プラグイン放棄」を避けることです。

プルリクエストの準備¶

短いバージョン¶

リポジトリをフォークします。
必要に応じて、上流からタグをフェッチします（メインのみをクローンした場合 git fetch --tags https://github.com/pytest-dev/pytest）。
スタイルガイドとコードチェックが遵守されるようにするために、pre-commit を有効にしてインストールします。
命名には PEP-8 に従います。
テストは tox を使用して実行されます:
```
tox -e linting,py39
```
上記のテスト環境は、通常、ほとんどのケースをローカルでカバーするのに十分です。
changelog エントリを書きます： changelog/2574.bugfix.rst、問題 ID 番号と feature、improvement、bugfix、doc、deprecation、breaking、vendor または trivial のいずれかを問題タイプとして使用します。
変更が些細なものであるか、ドキュメントの修正 (例えば、誤字や小さなセクションの言い換え) である場合を除き、アルファベット順で AUTHORS ファイルに自分を追加してください。

長いバージョン¶

"プルリクエスト" とは何ですか？プロジェクトのコア開発者にレビューとマージを希望する変更を通知します。プルリクエストは GitHub サーバーに保存されます。プルリクエストを送信すると、その変更の潜在的な修正について議論し、後でさらにコミットを追加することもできます。プルリクエストの仕組みについては、GitHub ヘルプセンターに優れたチュートリアルがあります。

ここに、pytest に特有の部分を含む簡単な概要があります：

pytest GitHub リポジトリをフォークします。フォークリポジトリ名として pytest を使用しても問題ありません。これはあなたのユーザーの下に存在するためです。
git を使用してフォークをローカルにクローンし、ブランチを作成します:
```
$ git clone git@github.com:YOUR_GITHUB_USERNAME/pytest.git
$ cd pytest
$ git fetch --tags https://github.com/pytest-dev/pytest
# now, create your own branch off "main":

    $ git checkout -b your-bugfix-branch-name main
```
"major.minor.micro" バージョン番号がある場合、バグ修正は通常マイクロリリースでリリースされ、機能はマイナーリリースでリリースされ、互換性のない変更はメジャーリリースでリリースされます。

ローカルでテストするにはタグが必要なので、メインリポジトリからタグを取得していることを確認してください。取得していないと思われる場合は、メインリポジトリをアップストリームとして設定し、タグをフェッチします:
```
$ git remote add upstream https://github.com/pytest-dev/pytest
$ git fetch upstream --tags
```
Git に関するヘルプが必要な場合は、このクイックスタートガイドに従ってください：https://git.wiki.kernel.org/index.php/QuickStart
pre-commit をインストールし、pytest リポジトリにフックします:
```
$ pip install --user pre-commit
$ pre-commit install
```
その後、pre-commit はコミットするたびに実行されます。

https://pre-commit.com/ は、コードスタイルとコードフォーマットの一貫性を確保するために、複数の言語の pre-commit フックを管理および維持するためのフレームワークです。
tox をインストールします

Tox はすべてのテストを実行するために使用され、テストを実行するための virtualenvs を自動的に設定します。 (暗黙的に https://virtualenv.pypa.io/en/latest/ を使用します):
```
$ pip install tox
```
すべてのテストを実行します

システムに Python 3.8 以降がインストールされている必要があります。テストを実行するのは次のコマンドを発行するだけで簡単です:
```
$ tox -e linting,py39
```
このコマンドは、"tox" ツールを使用して Python 3.9 に対してテストを実行し、"lint" コーディングスタイルチェックも実行します。
これで、ローカルの作業コピーを編集し、必要に応じて再度テストを実行できます。命名には PEP-8 に従ってください。

tox に異なるオプションを渡すことができます。例えば、Python 3.9 でテストを実行し、pytest にオプションを渡す (例えば、失敗時に pdb に入る) には次のようにします:
```
$ tox -e py39 -- --pdb
```
または、特定のテストモジュールでのみ Python 3.9 でテストを実行するには次のようにします:
```
$ tox -e py39 -- testing/test_config.py
```
コミット時に、必要に応じて pre-commit がファイルを再フォーマットします。
tox を使用する代わりにテストを直接実行することを好む場合は、仮想環境を作成し、dev エクストラを使用して編集可能なインストールを行うことをお勧めします:
```
$ python3 -m venv .venv
$ source .venv/bin/activate  # Linux
$ .venv/Scripts/activate.bat  # Windows
$ pip install -e ".[dev]"
```
その後、ファイルを編集して通常通り pytest を実行できます:
```
$ pytest testing/test_config.py
```
changelog に新しい変更履歴エントリを作成します。ファイル名は <issueid>.<type>.rst とし、issueid は変更に関連する問題の番号で、type は feature, improvement, bugfix, doc, deprecation, breaking, vendor または trivial のいずれかです。変更が pytest の文書化された動作に影響を与えない場合は、変更履歴エントリの作成を省略できます。
まだ追加されていない場合は、アルファベット順で AUTHORS ファイルに自分を追加してください。
テストが通り、変更に満足したら、コミットしてプッシュします:
```
$ git commit -a -m "<commit message>"
$ git push -u
```
最後に、次のデータを使用して GitHub ウェブサイトを通じてプルリクエストを送信します:
```
head-fork: YOUR_GITHUB_USERNAME/pytest
compare: your-branch-name

base-fork: pytest-dev/pytest
base: main
```

テストの作成¶

プラグインや pytest 自体のテストを作成する場合、しばしば pytester fixture を使用して "ブラックボックス" テストとして行います。

例えば、簡単なテストが通ることを確認するために次のように書くことができます：

def test_true_assertion(pytester):
    pytester.makepyfile(
        """
        def test_foo():
            assert True
    """
    )
    result = pytester.runpytest()
    result.assert_outcomes(failed=0, passed=1)

また、glob-like 式を使用してターミナルの実際の出力に基づいてチェックを行うことも可能です：

def test_true_assertion(pytester):
    pytester.makepyfile(
        """
        def test_foo():
            assert False
    """
    )
    result = pytester.runpytest()
    result.stdout.fnmatch_lines(["*assert False*", "*1 failed*"])

新しいテストを書くファイルを選ぶ際には、既存のファイルを見て、適していると思われるファイルがあるかどうかを確認してください。例えば、--lf オプションのバグに関する回帰テストは、cacheprovider.py に実装されているため、test_cacheprovider.py に入れるべきです。疑問がある場合は、最善の推測で PR を開き、コードを通じてこれを議論することができます。

開発チームに参加する¶

開発チームからの追加作業を必要とせずにプルリクエストを完了させた人は、希望すればコミットアクセスを得ることができます (忘れていた場合は、友好的なリマインダーを送ってください)。これは、あなたの貢献ワークフローに変更があることを意味するものではありません。全員が同じプルリクエストとレビューのプロセスを経ており、承認されない限り、自分のプルリクエストをマージすることはありません。ただし、レビュー後に他の貢献者からのプルリクエストを自分でマージできるため、開発プロセスにより完全に参加できるようになります。

マージ/スクワッシュのガイドライン¶

PR が承認され、main ブランチに統合する準備が整ったら、コミットを変更せずに マージ するか、すべてのコミットを単一のコミットに スクワッシュ するオプションがあります。

単一の PR コミット履歴の例に基づいて、進め方に関するいくつかのガイドラインを示します：

その他のコミット：
- X を実装
- test_a を修正
- 自分を AUTHORS に追加
- 修正！test_a を修正
- tests/test_integration.py を更新
- origin/main を PR ブランチにマージ
- tests/test_integration.py を更新
この場合、スクワッシュ マージ戦略を使用することをお勧めします：コミット履歴が少し乱雑です (軽蔑的な意味ではなく、変更が最終的に一緒にスクワッシュされることを知っているため、しばしば変更をコミットするだけです)、したがって、すべてを単一のコミットにスクワッシュするのが最善です。コミットメッセージを整理し、有用な詳細が含まれていることを確認する必要があります。
同じトピックに関連する個別のコミット：
- X を実装
- 自分を AUTHORS に追加
- X のために CHANGELOG を更新
この場合、スクワッシュ マージ戦略を使用することをお勧めします：上記の例のようにコミット履歴が「乱雑」ではありませんが、個々のコミットは全体としてあまり価値をもたらしません。特に数か月/数年後に変更を見た場合です。
それぞれのトピック (リファクタリング、リネームなど) を持つ個別のコミットですが、依然として大きなトピック/目的があります。
- 機能 Y の準備のためにクラス X をリファクタリングする
- 未使用のメソッドを削除する
- 機能 Y を実装する
この場合、マージ 戦略を使用することをお勧めします。各コミットはそれ自体で価値があり、全体として共通のトピックに役立つ場合でもです。後で履歴を確認するときに、未使用のメソッドの削除を個別のコミットとして持つことは、そのメソッドが最初に未使用になった経緯などの追加情報とともに役立ちます。
それぞれのトピックを持つ個別のコミットですが、コードベースの改善 (より現代的な技術の使用、型の改善、不要なものの削除など) 以外の大きなトピック/目的はありません。
- X の内部名を改善する
- Y に型注釈を追加する
- 不要な辞書アクセスを削除する
- Python の EOL により到達不能なコードを削除する
この場合、マージ 戦略を使用することをお勧めします。各コミットはそれ自体で価値があり、それぞれの情報は長期的に価値があります。

前述のように、これらは全体的なガイドラインであり、絶対的なルールではありません。このトピックは #12633 で議論されました。

バックポート PR (backport ラベルから自動的に作成されるもの) は常に スクワッシュ されるべきです。これにより、元の PR の作成者が保持されます。

次のパッチリリースのためのバグ修正のバックポート¶

Pytest は数週間または数か月ごとに機能リリースを行います。その間に、前の機能リリースに対してパッチリリースが行われ、バグ修正のみが含まれます。バグ修正は通常、リグレッションを修正しますが、次の機能リリース前にユーザーに届くべき変更である場合もあります。

例えば、最新リリースが 1.2.3 であり、1.2.4 にバグ修正を含めたいとします (実際の最新リリースについては https://github.com/pytest-dev/pytest/releases を確認してください)。この手順は次のとおりです。

まず、上記のように通常のプルリクエストでバグが main ブランチで修正されていることを確認してください。これに対する例外は、バグ修正が main に適用されなくなった場合です。

自動方法：

バックポートしたい PR に backport 1.2.x ラベルを追加します。これにより、1.2.x ブランチに対するバックポート PR が作成されます。

手動方法：

git checkout origin/1.2.x -b backport-XXXX # ここにメイン PR 番号を使用します
PR のマージコミットを merged メッセージで見つけます。例えば：

nicoddemus がコミット 0f8b462 を pytest-dev:main にマージしました
git cherry-pick -x -m1 REVISION # 上記で見つけたリビジョン (0f8b462) を使用します。
1.2.x をターゲットにした PR を開きます：
- メッセージの先頭に [1.2.x] を付けます。
- PR 本文を削除します。通常、重複するコミットメッセージが含まれています。

誰がバックポートを行うか¶

前述のように、バグはまず main で修正されるべきです (バグが以前のリリースでのみ発生する稀な場合を除く)。では、上記のバックポート手順を誰が行うべきでしょうか？

バグがコア開発者によって修正された場合、そのコア開発者がバックポートを行う主な責任があります。
しかし、多くの場合、マージは別のメンテナーによって行われ、その場合、時間があればバックポート手順を行うのが良いでしょう。
非メンテナーによって提出されたバグについては、通常、main で PR をマージしたコア開発者がバックポートを行うことが期待されます。
非メンテナーが main で修正されたがバックポートされていないバグに気付いた場合 (メンテナーが needs backport ラベルを適用するのを忘れた、または単に見逃したため)、バックポート付きの PR を開くことも歓迎されます。この手順は簡単で、プロジェクトのメンテナンスに非常に役立ちます。

上記のすべてはルールではなく、バックポートについて期待すべきことに関するガイドライン/提案に過ぎません。

バックポートは マージ ではなく スクワッシュ されるべきです。これにより、元の PR の作成者が正しく保持されます。

古い問題/PR の処理¶

古い問題/PR とは、pytest の貢献者が質問/変更を求めたが、著者が長い間それに答えたり実装したりしなかったもの、または人々が興味を失ったために議論が単に終わったものです。

人々が質問に答えたり、要求された変更を実装したりしない理由はたくさんあります。忙しくなったり、興味を失ったり、単に忘れてしまったりするかもしれませんが、事実としてこれはオープンソースソフトウェアでは非常に一般的です。

pytest チームはすべての問題とプルリクエストに本当に感謝していますが、毎日多くの問題とプルリクエストが提出される大量プロジェクトであるため、定期的にそれらを閉じることで古い問題と PR の数を減らそうとしています。この方法で問題/プルリクエストが閉じられるとき、それは問題/プルリクエストが取り組んでいるトピックの却下を意味するものではなく、単にキューをクリアし、メンテナーの作業をより管理しやすくする方法です。提出者は、後で自分の時間で問題/プルリクエストを再開することが常にできます。

いつ閉じるか¶

メンテナーが非活動のために問題/PR を閉じる時期を決定するために使用するいくつかの一般的なルールを以下に示します：

question または needs information ラベルが付いた問題：14 日間非活動後に閉じられます。
proposal ラベルが付いた問題：6 か月間非活動後に閉じられます。
プルリクエスト：1 か月後、著者に ping を送信する、リンクされた問題を更新する、または閉じることを検討します。ほぼ完了しているプルリクエストについては、チームはそれを完了してマージすることを検討する必要があります。

上記は 厳格なルールではなく、単なる ガイドライン であり、ケースバイケースで (そしてしばしば) 見直されることがあります。

プルリクエストを閉じる¶

プルリクエストを閉じるときは、それを提出した人が示した時間、労力、および関心を認識する必要があります。前述のように、チームの意図は停滞したプルリクエストを完全に却下することではなく、単にキューをクリアすることです。そのため、古くなったプルリクエストを閉じるときは、以下のようなメッセージが正当化されます：

こんにちは <contributor>、

まず最初に、この作業に費やした時間と労力に感謝します。 pytest チームはそれを深く感謝しています。

しかし、この PR を更新してからしばらく経っていることに気付きました。 pytest は高活動プロジェクトであり、毎日多くの問題/PR が開かれているため、どの PR がマージの準備ができているか、レビューが必要か、またはさらに注意が必要かを追跡するのはメンテナーにとって難しいです。

したがって、これらの理由から、キューをクリーンアップするために一時的に PR を閉じるのが最善だと考えていますが、これはあなたの変更を拒否するものではありません。準備ができたら、この PR を再開することをお勧めします (ボタンをクリックするだけです)。

再度、この作業に費やした時間に感謝し、後でこれに戻ることを願っています！

<さようなら>

問題を閉じる¶

問題を修正するためにプルリクエストが提出された場合、PR の説明および/またはコミットに closes #XYZW のようなテキストを追加します (XYZW は問題番号です)。詳細については、GitHub docs を参照してください。

問題がユーザーエラー (例：機能の誤解) による場合、ユーザーに対して問題が実際には問題ではない理由を丁寧に説明し、追加の質問がない場合は問題を閉じるように依頼してください。元のリクエスターが応答しない場合、問題は上記の古い問題/PR の処理セクションで説明されているように処理されます。