PDEP-1: 目的とガイドライン

PDEPの定義、目的、範囲

PDEP (pandas enhancement proposal) は、PythonのPEPやNumPyのNEPと同様に、pandasにおける**主要な**変更提案です。

バグ修正や概念的に小さな変更（例：関数にパラメータを追加する）は、PDEPの範囲外です。PDEPは、すぐに明らかではなく、pandasコミュニティ全体が今後の変更の可能性を認識する必要がある変更に使用されるべきです。このような変更は、実装前に詳細なドキュメントが必要であり、多くの場合、コミュニティ内で大規模な議論につながります。

PDEPは、ユーザー向けの変更、内部的な変更、重要な議論に適しています。PDEPに値するトピックの例としては、APIの大幅な変更、動作の破壊的変更、pandasから別のリポジトリへのモジュールの移動、またはpandasブロックマネージャーのリファクタリングなどがあります。どの問題がPDEPプロセス全体を必要とするだけの範囲を持っているかを判断することは、常に容易ではありません。コアチーム間で十分なコンセンサスがあり、コミュニティへの影響が最小限の単純なAPI変更もあります。一方、問題が物議を醸す場合、つまり大規模な議論を生じた場合、議論を形式化し文書化して、より広いコミュニティが参加しやすくなるように、PDEPを開くことを提案できます。文脈として、PDEPであった可能性のある問題のリストを参照してください。

PDEPガイドライン

対象読者

PDEPは誰でも利用できる公開文書ですが、PDEPを作成する際に考慮すべき主な利害関係者は以下のとおりです。

PDEP作成者

誰でもPDEPを提案できますが、コアメンバーは、コアコントリビューター以外による提案について助言するために関与する必要があります。コミュニティメンバーとしてPDEPを提出するには、issueでPDEPの概念を提案し、協力するpandasチームメンバーを見つけてください。彼らはPDEPプロセスについてアドバイスし、PDEPリポジトリに提出された際にはPDEPのアドバイザーとしてリストされる必要があります。

ワークフロー

PDEPの可能な状態は以下のとおりです。

次に、PDEPが従うことができるワークフローについて説明します。

PDEPの提出

PDEPを提案するには、`web/pdeps/`に新しいファイルを追加するPRを作成します。ファイルはマークダウンファイルで、`web/pdeps/0001.md`を期待される形式の参照として使用できます。

PDEPの初期ステータスは`Status: 議論中`になります。PDEPの準備が整い、コアチームの承認を得たら、`Status: 承認済み`に変更されます。

承認済みPDEP

PDEPは、提案が実装する価値があると判断された場合のみ、コア開発チームによって承認できます。決定は、pandasガバナンス文書に詳述されているプロセスに基づいて行われます。一般的に、PRがマージされる前に、複数の承認が必要です。そして、マージ時に`変更を要求する`レビューがあってはいけません。

PDEPが承認されると、期限のない完了タイムラインで、PDEPの実装に向けて任意の貢献を行うことができます。pandasへのコントリビューターが、異なる優先順位を持つ異なるソースから支払われたボランティアと開発者の混合であるため、pandasの開発は理解し予測するのが困難です。PDEPの実装に興味がある企業、機関、または個人、またはpandasのロードマップへの進捗状況を一般的に見たい場合は、コントリビューションページで支援方法を確認してください。

実装済みPDEP

PDEPが実装され、pandasのメインブランチで使用可能になると、そのステータスは`Status: 実装済み`に変更されます。これにより、PDEPがロードマップや将来の計画の一部ではなく、すでに発生した変更であることが視覚的にわかります。PDEP実装が利用可能な最初のpandasバージョンも、例として`Implemented: v2.0.0`を使用してPDEPヘッダーに含まれます。

拒否済みPDEP

最終的な決定が、その実装がプロジェクトの最善の利益にならない場合、PDEPは拒否される可能性があります。拒否されたPDEPは、承認されたPDEPと同じくらい役に立ちます。なぜなら、価値のある議論があり、pandasへの変更に関する決定が行われるからです。それらは`Status: 拒否済み`でマージされるため、何が議論され、議論の結果がどうなるかがわかります。PDEPは、例えば、下位互換性のない良いアイデアや、破壊的な変更が実装する価値がないと判断された場合など、さまざまな理由で拒否される可能性があります。

無効なPDEP

適切なドキュメントが含まれていない、範囲外である、またはその他の理由でコミュニティにとって役に立たない提出されたPDEPについては、拒否としてマージする代わりに、作成者との議論の後、PRが閉じられます。これは、承認されたPDEPと同じくらい良いドキュメントを含むべきである拒否されたPDEPのリストにノイズを追加しないためです。ただし、最終的な決定は変更を実装しないことでした。

PDEPの進化

ほとんどのPDEPは、承認された後も変更されることは想定されていません。変更に合意し、実装されると、PDEPは開発が行われた理由と議論の詳細を理解するためにのみ役立ちます。

しかし、いくつかのケースでは、PDEPを更新できます。たとえば、このPDEP（PDEP-1）のような手順またはポリシーを定義するPDEP。または、実装を試みた後、元のPDEPを無効にする新しい知識が得られ、変更が必要になった場合。元のPDEPに特定の変更を加える必要がある場合は、編集され、その`Revision: X`ラベルが1つ増え、`PDEP-N履歴`セクションにメモが追加されます。これにより、読者はPDEPが変更されたことを理解し、混乱を避けることができます。

文脈のための、PDEPであった可能性のある問題のリスト

潜在的なPDEPの明確な例

境界線上の例

`DataFrame`や`Series`などのコア機能への小さな変更は、ユーザーに大きな影響を与える可能性があるため、常にPDEP候補として考慮する必要があります。しかし、他の機能における同じ種類の変更は、良いPDEP候補にはなりません。つまり、変更がどれほど小さくても、物議を醸す議論はPDEP候補です。より多くの注意と/または正式な意思決定プロセスが役立つかどうかを検討してください。以下は、私たちの意図を明確にするのに役立つと思われるいくつかの例です。

PDEP-1履歴