プルリクエストのガイドライン#
プル リクエスト (PR) は、Matplotlibs のコードとドキュメントに貢献するためのメカニズムです。
プル リクエスト レビュアー向けの概要#
ノート
コミット権を持っている場合は、それらを使用することが信頼されています。 PR のレビューとマージにご協力ください。
寄稿者に対して辛抱強く親切に対応してください。
内容のトピック:
機能/バグ修正は合理的ですか?
PR はコーディング ガイドラインに準拠していますか?
ドキュメント(ドキュメント文字列、サンプル、新機能、API の変更) は更新されていますか?
組織のトピック:
詳細なガイドライン#
ドキュメンテーション#
すべての新機能は文書化する必要があります。新しいモジュールの場合は、新しい rst ファイルを API ドキュメントに追加することを忘れないでください。
各高レベルのプロット関数
Examplesには、docstring のセクションに小さな例が含まれている必要があります。これは、メソッドを示すためにできるだけ単純にする必要があります。より複雑な例は、ディレクトリ内の専用の例ファイルに入れる必要がexamplesあります。これは、ドキュメントの例ギャラリーにレンダリングされます。ドキュメントを作成し、すべての書式設定の警告が対処されていることを確認してください。
ドキュメンテーションスタイル ガイドについては、ドキュメントの作成を参照してください。
変更が主要な新機能である場合は、エントリを に追加して
doc/users/whats_new.rstください。下位互換性のない方法で API を変更する場合は、関連する
doc/api/next_api_changes/のサブディレクトリ (おそらくサブディレクトリ) にファイルを追加して、ドキュメント化してくださいbehavior/。
ラベル#
ラベルを設定する権限がある場合は、説明的なラベルで PR にタグを付けます。ラベルのリストを参照してください。
PR がホイール ビルディング アクションに変更を加えた場合は、「Run cibuildwheel」ラベルを追加してホイールのテストを有効にします。
マイルストーン#
次のルールに従ってマイルストーンを設定します。
新機能と API の変更は、次のマイナー リリースのマイルストーンです
v3.X.0。バグ修正と docstring の変更は、次のパッチ リリースのマイルストーンです
v3.X.Yドキュメントの変更(すべての .rst ファイルとサンプル) はマイルストーンです
v3.X-doc
複数のルールが適用される場合は、上記のリストから最初に一致するものを選択します。
マイルストーンの設定は、PR がそのリリースにマージされることを意味または保証するものではありませんが、マージされる場合はどのリリースに含まれるかを示します。
これらの PR はすべてメイン ブランチをターゲットにする必要があります。マイルストーン タグは、対応するブランチを持つマイルストーンの自動バックポートをトリガーします。
マージ#
ドキュメントと例は、最初のレビュアーによってマージされる場合があります。「これは以前よりも優れていますか?」というしきい値を使用します。審査基準として。
コードの変更 (
srcまたは内libのすべて) については、少なくとも 2 人のコア開発者 (コミット権限を持つ開発者) がすべてのプル リクエストを確認する必要があります。PR を最初にレビューして変更を承認する場合は、GitHubの「レビューの承認」 ツールを使用してそのようにマークしてください。あなたが後続のレビュアーである場合は、レビューを承認してください。これ以上レビューする必要がないと思われる場合は、PR をマージしてください。すべての API の変更が のサブディレクトリのいずれかにあるファイルに文書化されていることを確認し
doc/api/next_api_changes、重要な新機能のエントリが にあることを確認してくださいdoc/user/whats_new。PR にすでに肯定的なレビューがある場合、コア開発者 (最初のレビュー担当者など) は、その PR をマージするために擁護する場合があります。そのためには、GitHub と開発メーリング リストの両方ですべてのコア開発者に ping を送信し、PR に「Merge with single review?」というラベルを付ける必要があります。ラベル。その後、他のコア開発者は、PR をレビューしてマージまたは拒否するか、マージする前に 2 回目のレビューを要求することができます。1 週間以内にそのような 2 回目のレビューを求める人がいない場合は、その 1 回のレビューに基づいて PR をマージできます。
コア開発者は、一度に 1 つの PR のみを擁護する必要があり、擁護された PR の流れを合理的に保つように努める必要があります。
CI の破損を解除するための「小さな」パッチを除き、または別のレビュアーが明示的に許可する場合を除いて、セルフ マージしないでください (たとえば、「Modulo CI の受け渡しを承認し、緑色の場合はセルフ マージすることができます」)。
自動テスト#
プル リクエストが作成または更新されるたびに、サポートされているすべてのプラットフォームとバージョンの Python でさまざまな自動テスト ツールが実行されます。
マージする前に、Linting、GitHub Actions、AppVeyor、CircleCI、および Azure パイプラインがパスしていることを確認してください (すべてのチェックは、プル リクエストの GitHub ページの下部にリストされています)。テストの失敗の原因を見つけるためのヒントを次に示します。
Lintingが失敗した場合、プル リクエストの差分に注釈としてリストされるコード スタイルの問題があります。
GitHub Actions または AppVeyor の実行が失敗した場合は、ログで を検索します
FAILURES。後続のセクションには、失敗したテストに関する情報が含まれます。CircleCI が失敗する場合は、ドキュメントに reStructuredText スタイルの問題がある可能性があります。CircleCI ログで を検索します
WARNING。Azure パイプラインがイメージ比較エラーで失敗した場合、Azure ジョブの成果物としてイメージを見つけることができます。
GitHub PR ページのチェックでDetailsをクリックします。
[ Azure Pipelines の詳細を表示] をクリックして、Azureに移動します。
概要ページでは、アーティファクトは [関連]セクションに一覧表示されます。
Codecov と LGTM は現在、情報提供のみを目的としています。彼らの失敗は必ずしもブロッカーではありません。
toxは自動テストでは使用されません。ローカルでのテスト用にサポートされています。
変更をテストする必要がないことがわかっている場合 (これは非常にまれです!)、コミット メッセージにまたは を含めることで、特定のコミットのすべての CI をスキップできます。CI のサブセットのみを実行する必要があることがわかっている場合 (たとえば、プレーンな reStructuredText のブロックを変更し、CircleCI のみを実行して結果をレンダリングする場合)、以下を使用して個々のコミットで個々の CI をスキップすることもできます。コミット メッセージの部分文字列:
[ci skip][skip ci]GitHub アクション:
[skip actions]AppVeyor: (コミットの最初の行にある必要があります)
[skip appveyor]Azure パイプライン:
[skip azp]サークルCI:
[skip circle]
コミット数とスカッシュ数#
スカッシングはケースバイケースです。貢献者の負担、比較的クリーンな履歴の保持、および二分に使用できる履歴の保持の間でバランスが取られます。私たちが本当に厳密に行っているのは、バイナリ ファイル (複数のテスト イメージの再生成など) を排除し、アップストリーム マージを削除する場合のみです。
特にドキュメンテーションやサンプル PR の場合は、完璧であることを善の敵にしないでください。小さな提案をたくさんしている場合は、元のブランチに対して PR を開くか、コントリビューター ブランチに変更をプッシュするか、PR をマージしてからアップストリームに対して新しい PR を開きます。
コントリビューター ブランチにプッシュする場合は、何をしたかを説明するコメントを残してください。PR のコードまたは意図に大幅な変更を加える場合は、まず寄稿者に確認してください。
ブランチとバックポート#
現在のブランチ番号
現在アクティブなブランチは次のとおりです。
- 主要
現在の開発バージョン。今後のマイナー リリース ( v3.N.0 ) は、ここから分岐します。
- v3.Nx
Matplotlib 3.N のメンテナンス ブランチ。今後のパッチ リリースは、ここから分岐します。
- v3.NM-doc
現在のリリースのドキュメント。パッチ リリースでは、これは新しいリリースの適切な名前のブランチに置き換えられます。
プルリクエストのブランチ選択#
通常、すべてのプル リクエストはメイン ブランチをターゲットにする必要があります。
他の分岐は、自動または 手動で供給されます。他のブランチを直接ターゲットにすることは、特別なメンテナンス作業で必要になることはめったにありません。
バックポート戦略#
常にパッチ リリース ブランチ ( v3.Nx ) にバックポートします。
重要なバグ修正 (segfault、インポートの失敗、ユーザーが回避できないこと)
最後の 2 つのリリースに対する回帰の修正。
それ以外のすべて (古いリリースに対するリグレッション、ユーザーがコードで回避できるバグ/API の不一致) はケースバイケースであり、リスクは低く、バックポートを支持して支援する人が必要です。
ドキュメント ブランチ ( v3.NM-doc )にバックポートされる唯一の変更はdoc、、、examplesまたはへの変更tutorialsです。docstring のみの変更に対する変更、libまたはそれsrcを含む変更は、このブランチにバックポートしないでください。
自動バックポート#
meseeksdev ボットを使用して、マイルストーンに基づく正しいメンテナンス ブランチ ベースにマージを自動的にバックポートします。適切に機能させるには、マージする前にマイルストーンを設定する必要があります。コミット権がある場合は
、PR にメッセージを残して、マージ後に手動でボットをトリガーすることもできます。競合がある場合は、バックポートを手動で行う必要があることを meseekdevs が通知します。@meeseeksdev backport to BRANCH
ターゲット ブランチは、それ自体の行にマイルストーンの説明を入れることによって構成されます。on-merge: backport to
TARGETBRANCH
ボットが期待どおりに動作しない場合は、 Meseeksdevに問題を報告してください。
手動バックポート#
バックポートを行うときは、meseekdev で使用されているフォームをコピーしてください
。競合を手動で解決する必要がある場合は、それらと、コミット メッセージでそれらをどのように解決したかを書き留めてください。Backport PR #XXXX: TITLE OF PR
次の前提で、メインから v2.2.x へのバックポートを行います。
matplotlibmatplotlib/matplotlib リポジトリの読み取り専用リモート ブランチです。
これTARGET_SHAは、バックポートするマージ コミットのハッシュです。これは、GitHub PR ページから (マージ通知のある UI で)、または git CLI ツールを介して読み取ることができます。
v2.2.x既にローカル ブランチがあり(そうでない場合は
)、リモート ポインティング
が呼び出されていると仮定します。git checkout -b v2.2.xhttps://github.com/matplotlib/matplotlibupstream
git fetch upstream
git checkout v2.2.x # or include -b if you don't already have this.
git reset --hard upstream/v2.2.x
git cherry-pick -m 1 TARGET_SHA
# resolve conflicts and commit if required
競合のあるファイルは によって一覧表示される可能性があり、手動で修正する必要があります ( で検索)。競合が解決したら、ファイルをブランチに再度追加してから、チェリーピックを続行する必要があります。git status>>>>>
git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue
アップストリームに直接プッシュするか、PR を開くかは、あなたの裁量で行ってください。v2.2.xではなく、必ず上流のブランチに対してプッシュまたは PR してmainください。