PDEP-1: 目的とガイドライン
- 作成日: 2022年8月3日
- ステータス: 承認済み
- 議論: #47444, #51417
- 著者: Marc Garcia, Noa Tamir
- 改訂: 3
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が承認されるかどうかの最終決定権を持つコア開発チーム
- pandasおよびその他の関連プロジェクトの貢献者、および経験豊富なユーザー。すべての視点が考慮されるよう、彼らのフィードバックは強く推奨され、高く評価されます。
- より広範なpandasコミュニティ、特にユーザー。彼らは提案に対してフィードバックを持つ場合と持たない場合がありますが、プロジェクトの将来の方向性を知っておく必要があり、理解できる必要があります。
PDEPの著者
誰でもPDEPを提案できますが、コアメンバーは非コア貢献者による提案について助言するために協力する必要があります。コミュニティメンバーとしてPDEPを提出するには、イシューでPDEPの概念を提案し、協力するpandasチームメンバーを見つけてください。彼らはPDEPプロセスについて助言することができ、PDEPがPDEPリポジトリに提出される際に、PDEPの助言者として記載されるべきです。
ワークフロー
論理的根拠
私たちのワークフローは、コンセンサスを求めるプロセスを支援し、現在の著者と将来の著者、および議決権を持つメンバーに明確性を提供するために作成されました。これは厳格なポリシーではなく、何らかの形で決定を「強制」または「こっそり行う」ような形でこれを利用しようとするいかなる解釈も推奨しません。私たちは、すべてのコミュニティメンバーからの透明性、活発な議論、フィードバック、妥協を期待し、奨励します。
PDEPの状態
PDEPの可能な状態は以下の通りです。
- ドラフト
- 議論中
- 承認済み
- 実装済み
- 却下済み
- 撤回済み
次に、PDEPがたどることができるワークフローについて説明します。
PDEPの提出
PDEPの提案は、web/pandas/pdeps/に新しいファイルを追加するPRを作成することによって行われます。このファイルはマークダウンファイルであり、期待される形式の参照としてweb/pandas/pdeps/0001-purpose-and-guidelines.mdを使用できます。
PDEPの初期ステータスは`Status: Draft`となります。意思決定プロセスに進む準備ができた場合、著者によって`Status: Under discussion`に変更されます。
PDEP議論のタイムライン
PDEPの議論は最大60日間開かれたままになります。この期間は、迅速に回答できない可能性のあるボランティアの参加を可能にし、参加者からの提案や考慮事項に基づいて変更を行う十分な時間を提供することを目的としています。同様に、その後の投票期間は15日間開かれたままになります。
PDEPに関する議論を可能にし、奨励するために、通知スケジュールに従います。以下の各ステップで、pandasチームとpandas-devメーリングリストはGitHubとEメールで通知されます。
- PDEPが議論の準備が整ったとき。
- 30日後。議論の残り期間が最大30日であること、および次の15日間に議論がない場合は投票が行われる旨を通知します。
- 45日後。議論の残り期間が最大15日であること、および15日後に投票が行われる旨を通知します。
- 投票期間が開始されたとき（60日後、またはそれ以前の投票の場合）、投票期間が残り15日であることを通知します。
- 投票開始から10日後、投票期間が残り5日であることを通知します。
議論開始から30日後、未対応のコメントがないまま15日が経過した場合、著者は投票期間開始まで残り15日であることを早めにリマインドすることで、議論期間を早期に終了させることができます。
投票
投票期間が開始されると、PDEPの議論プルリクエストにリンクするVOTE issueが作成されます。議決権を持つ著者を含め、各議決権メンバーは、以下のコメントのいずれかを追加することで投票できます。
- +1: 承認
- 0: 棄権
- 理由: 1文の理由が必要。
- -1: 不承認
- 理由: 1文の理由が必要。
不承認票には、PDEP議論イシューへの事前の参加が必要です。
議決権を持たないメンバーによる公開VOTEイシューへのコメントは削除されます。
投票期間が終了すると、どの投票者も、承認票の合計w、棄権票の合計x、不承認票の合計y、VOTEイシューに回答しなかった議決権メンバーの数zという形式で、コメントに投票を集計できます。投票の集計には、定足数が達成されたかどうかが記載されます。
定足数と多数決
PDEPの投票が提案の承認につながるには、定足数が必要です。すべての投票（棄権を含む）は定足数に数えられます。定足数は、次の2つの値の低い方として計算されます。
- 11人の議決権メンバー
- 議決権メンバーの50%
定足数が満たされた場合、棄権しない投票の70%の過半数も必要です。つまり、承認票と不承認票の70%が賛成でなければなりません。
したがって、棄権票は定足数には数えられますが、過半数には数えられません。議決権を持つメンバーは、議論に参加し、提案に異議があるものの、提案の進行を止めたり、完全な支持を示したりしたくない場合に、棄権を選択することができます。
投票期間終了までに定足数が達成されなかった場合、PDEPは承認されません。そのステータスは却下に変更されます。
承認済みPDEP
PDEPが承認されると、完了期限は無期限で、PDEPの実装に向けてあらゆる貢献を行うことができます。pandasへの貢献者はボランティアと様々な財源から報酬を得ている開発者の混合であり、優先順位も異なるため、pandasの開発を理解し予測することは困難です。PDEPが実装されることに関心のある企業、機関、または個人、あるいはpandasのロードマップの進捗を全体的に確認したい場合は、貢献ページで協力できる方法を確認してください。
実装されたPDEP
PDEPが実装され、pandasのメインブランチで利用可能になると、そのステータスは`Status: Implemented`に変更されます。これにより、PDEPがロードマップや将来の計画の一部ではなく、すでに起こった変更であることが明確になります。PDEPの実装が利用可能になる最初のpandasバージョンも、例えば`Implemented: v2.0.0`のようにPDEPヘッダーに含まれます。
却下されたPDEP
PDEPは、その実装がプロジェクトの最善の利益にならないという最終決定が下された場合、却下されることがあります。却下されたPDEPは、議論する価値のある議論があり、pandasへの変更に関する決定が下されるため、承認されたPDEPと同様に有用です。これらは`Status: Rejected`としてマージされ、何が議論され、議論の結果がどうであったかという可視性が確保されます。PDEPはさまざまな理由で却下される可能性があり、例えば、後方互換性のない優れたアイデアで、破壊的な変更が実装する価値がないと判断される場合があります。
PDEPの著者自身がPDEPが実際には悪いアイデアであると判断した場合、または広く支持されていない、あるいは競合する提案の方が優れた代替案であると受け入れた場合、最終決定が下される前にPDEPの著者（たち）がPDEPを撤回すること（`Status: Withdrawn`）もできます。
著者は、却下または撤回されたPDEPを再提出することを選択できます。その場合、さらなる議論や修正された提案が異なる結果につながる可能性があると信じるかどうかについて、著者の判断に委ねられます。その後、以前却下されたPDEPへのリンクを含む新しいPDEPが作成されます。
無効なPDEP
提出されたPDEPで、適切な文書が含まれていない、範囲外である、またはその他の理由でコミュニティに役立たない場合、PRは却下としてマージされるのではなく、著者との議論の後にクローズされます。これは、承認されたPDEPと同様に優れた文書を含むべきだが、最終的な決定が変更を実装しないことだった却下されたPDEPのリストにノイズを追加することを避けるためです。
PDEPの進化
ほとんどのPDEPは、承認後は変更されないと予想されます。変更に関する合意が形成され、それらが実装されると、PDEPは開発がなぜ行われたのか、そして議論の詳細を理解するためにのみ役立つでしょう。
しかし、場合によっては、PDEPが更新されることがあります。たとえば、このPDEP-1のように、手順やポリシーを定義するPDEP。または、実装を試みた後、元のPDEPを時代遅れにする新しい知識が得られ、変更が必要になる場合です。元のPDEPに特定の変更が行われる場合、これは編集され、その`Revision: X`ラベルは1つ増え、`PDEP-N history`セクションに注記が追加されます。これにより、読者はPDEPが変更されたことを理解し、混乱を避けることができます。
PDEPとなりえた問題のリスト（参考）
潜在的なPDEPの明確な例
- 多くの既存メソッドに新しいパラメータを追加したり、多くの箇所で既存のパラメータを非推奨にしたりする場合。例えば、
numeric_onlyの非推奨化(GH-28900)は多くのメソッドに影響を与え、PDEPになり得た。- 新しいデータ型を追加すると、そのデータ型を処理する必要があるさまざまな場所に影響を与えます。このような広範な影響はPDEPを必要とします。例えば、
Categorical(GH-7217, GH-8074),StringDtype(GH-8640),ArrowDtype- 既存の動作における重大な（破壊的な）変更。例えば、
- コピー/ビューの変更 (GH-36195)
- プロジェクトに広範な影響を与える新しいPython機能のサポート。例えば、
- pandas内での型ヒントのサポートと
pandas-stubsの作成 (GH-43197, GH-45253) - 新しい必須の依存関係。
- プロジェクトからのモジュールの削除、または別のリポジトリへの分離
- あまり使用されていないI/Oコネクタを別のリポジトリに移動する GH-28409
- 貢献者のプロセスにおける重大な変更はユーザーには影響を与えませんが、貢献者間の構造化された議論からは恩恵を受けます。例えば、
- ビルドシステムをmesonに変更する (GH-49115)
際どい例
DataFrameやSeriesといったコア機能の小さな変更は、ユーザーに大きな影響を与える可能性が高いため、常にPDEP候補として検討すべきです。しかし、他の機能における同じ種類の変更は、PDEP候補として適切ではないでしょう。とはいえ、どんなに小さな変更であっても議論の的となった場合はPDEP候補となります。より多くの注意や正式な意思決定プロセスが役立つかどうかを検討してください。以下に、私たちの意味を明確にするのに役立つと思われるいくつかの例を示します。
- APIの破壊的な変更、またはその議論はPDEPになる可能性があります。例えば、
value_countsの結果の名称変更 (GH-49497)。当初はPDEPの範囲を正当化するものではありませんが、後に破壊的な変更として実行すべきか、非推奨化すべきかについての議論が浮上し、PDEPプロセスから恩恵を受ける可能性があります。- 既存のメソッドに新しいメソッドやパラメータを追加することは、通常、非コア機能の場合はPDEPを必要としません。例えば、
dropna(percentage)(GH-35299) もTimestamp.normalize()(GH-8794) も、PDEPを必要としなかったでしょう。- 一方、
DataFrame.assign()は必要とするかもしれません。後方互換性の問題がない単一のメソッドである一方で、コア機能でもあり、議論は非常に目立つべきです。 - 単一のメソッドを非推奨にする、または削除することは、ほとんどの場合PDEPを必要としません。
- とはいえ、
DataFrame.append(GH-35407) は、PDEPの好候補となるコア機能の非推奨化の例です。 - コアpandasメソッドのパラメータのデフォルト値を変更することも、もう一つの際どいケースです。例えば、
DataFrame.groupbyおよびSeries.groupbyにおけるdropnaのそのような変更は、PDEPになる可能性があります。- 新しいトップレベルモジュールや、内部クラスの公開。例えば、
pandas.api.typing(GH-48577) の追加は比較的小規模であり、必ずしもPDEPを必要としないでしょう。