PDEP-1: 目的和指南

PDEP 定义、目的和范围

PDEP(pandas 增强提案)是对 pandas 中 **重大** 更改的提案,类似于 Python 的 PEP 或 NumPy 的 NEP

错误修复和概念上较小的更改(例如,向函数添加参数)不在 PDEP 的范围内。PDEP 应该用于非立即且非显而易见的更改,当 pandas 社区中的每个人都需要意识到即将发生的更改的可能性时。此类更改需要在实施之前进行详细的文档记录,并且经常会导致社区内进行重大讨论。

PDEP 适用于面向用户的更改、内部更改和重大讨论。值得进行 PDEP 的主题示例包括实质性的 API 更改、破坏性行为更改、将模块从 pandas 移动到单独的存储库或 pandas 块管理器重构。并非总是很容易知道哪个问题有足够的范围来需要完整的 PDEP 流程。一些简单的 API 更改在核心团队中达成了一致,并且对社区的影响最小。另一方面,如果一个问题变得有争议,即它引发了重大讨论,则可以建议打开一个 PDEP 来正式化和记录讨论,使更广泛的社区更容易参与。有关上下文,请参阅 可能成为 PDEP 的问题列表

PDEP 指南

目标受众

PDEP 是一份公开文件,任何人都可以访问,但在撰写 PDEP 时需要考虑的主要利益相关者是

PDEP 作者

任何人都可以提出 PDEP,但核心成员应该参与,为非核心贡献者提出的提案提供建议。要作为社区成员提交 PDEP,请在 问题 上提出 PDEP 概念,并找到 pandas 团队成员进行合作。他们可以就 PDEP 流程提供建议,并在 PDEP 提交到 PDEP 存储库时被列为顾问。

工作流程

PDEP 可能处于以下状态

接下来将描述 PDEP 可以遵循的工作流程。

提交 PDEP

提出 PDEP 是通过创建一个 PR 来完成的,该 PR 将一个新文件添加到 web/pdeps/ 中。该文件是一个 markdown 文件,您可以使用 web/pdeps/0001.md 作为预期格式的参考。

PDEP 的初始状态将为 Status: Under discussion。当 PDEP 准备就绪并获得核心团队的批准时,这将更改为 Status: Accepted

已接受的 PDEP

只有核心开发团队才能接受 PDEP,如果该提案被认为值得实施。决策将基于 pandas 治理文档 中详细说明的流程。一般来说,在 PR 合并之前需要多个批准。合并时不应该有任何 Request changes 审查。

一旦 PDEP 被接受,就可以对 PDEP 的实施做出任何贡献,并具有开放式的完成时间线。pandas 的开发很难理解和预测,因为 pandas 的贡献者是来自不同来源、具有不同优先级的志愿者和开发人员的混合体。对于有兴趣看到 PDEP 被实施的公司、机构或个人,或者一般来说希望看到 pandas 路线图的进展,请查看 贡献页面 中如何提供帮助。

已实现 PDEP

一旦 PDEP 在 pandas 的主分支中实现并可用,其状态将更改为 Status: Implemented,以便能够直观地看到该 PDEP 不再属于路线图和未来计划,而是一项已经完成的更改。PDEP 实现可用的第一个 pandas 版本也将包含在 PDEP 标题中,例如 Implemented: v2.0.0

被拒绝的 PDEP

当最终决定不实施 PDEP 对项目最有利时,可以拒绝该 PDEP。被拒绝的 PDEP 与被接受的 PDEP 一样有用,因为它们包含了值得讨论的内容,以及关于 pandas 更改的决策。它们将被合并为 Status: Rejected,以便能够直观地了解讨论的内容以及讨论的结果。PDEP 可能会因各种原因被拒绝,例如,一些好主意可能不向后兼容,而这些破坏性更改被认为不值得实施。

无效的 PDEP

对于提交的 PDEP,如果它们不包含适当的文档,超出范围,或因其他任何原因对社区没有用处,则在与作者讨论后,将关闭 PR,而不是将其合并为拒绝。这样做是为了避免在被拒绝的 PDEP 列表中添加噪音,该列表应该包含与被接受的 PDEP 一样好的文档,但最终决定不实施这些更改。

PDEP 的演变

大多数 PDEP 在被接受后预计不会发生变化。一旦对更改达成一致,并实施了这些更改,PDEP 将仅用于了解开发的原因以及讨论的细节。

但在某些情况下,可以更新 PDEP。例如,定义过程或策略的 PDEP,例如本 PDEP (PDEP-1)。或者,在尝试实施后,获得的新知识使原始 PDEP 过时,需要进行更改。当需要对原始 PDEP 进行特定更改时,将对其进行编辑,其 Revision: X 标签将增加 1,并且将在 PDEP-N history 部分添加注释。这将使读者了解 PDEP 发生了变化,并避免混淆。

可能作为 PDEP 的问题列表,以供参考

潜在 PDEP 的清晰示例

边界示例

对核心功能(如 DataFrameSeries)的小更改应始终被视为 PDEP 候选,因为它很可能对用户产生重大影响。但其他功能中的相同类型更改将不是好的 PDEP 候选。也就是说,任何讨论,无论更改有多小,只要变得有争议,都是 PDEP 候选。考虑是否需要更多关注和/或正式的决策过程。以下是一些我们希望可以帮助澄清我们在此含义的示例

PDEP-1 历史