pandas 维护#

本指南面向 pandas 的维护者。对于希望了解 pandas 开发流程以及成为维护者所需步骤的贡献者来说，这也可能很有趣。

主要的贡献指南位于 贡献给 pandas。

角色#

pandas 使用两个级别的权限：分流（triage）和核心（core）团队成员。

分流成员可以标记和关闭 issue 和 pull request。

核心团队成员可以标记和关闭 issue 和 pull request，并可以合并 pull request。

GitHub 发布了完整的权限列表。

任务#

pandas 主要是一个志愿者项目，因此不应将这些任务解读为对分流和维护者的“期望”。相反，它们是对成为维护者意味着什么的通用描述。

  • 分流新提交的 issue（参见 Issue 分流）

  • 审查新开启的 pull request

  • 回应现有 issue 和 pull request 的更新

  • 推动关于停滞 issue 和 pull request 的讨论和决策

  • 在 API 设计问题上提供经验/智慧，以确保一致性和可维护性

  • 项目组织（组织/参加开发者会议，代表 pandas）

https://matthewrocklin.com/blog/2019/05/18/maintainer 可能是有趣的背景阅读材料。

Issue 分流#

分流是处理社区报告的 issue 的重要第一步，即使是部分贡献也是帮助维护 pandas 的绝佳方式。只有在完成以下所有步骤后，才能移除“Needs Triage”标签。

以下是分流新开启 issue 的典型工作流程。

  1. 感谢报告者开启 issue

    issue 追踪器是许多人除了使用库之外，与 pandas 项目本身进行的首次互动。因此，我们希望它是一个受欢迎、愉快的体验。

  2. 是否提供了必要的信息？

    理想情况下，报告者会填写 issue 模板，但许多人没有。如果缺少关键信息（例如他们使用的 pandas 版本），请随时要求提供，并将 issue 标记为“Needs info”。报告应遵循错误报告和增强功能请求中的指南。如果他们没有遵循模板，您可能需要链接到那里。

    确保标题准确反映了 issue。如果不清楚，请自行编辑。

  3. 这是重复的 issue 吗？

    我们有许多未解决的 issue。如果一个新 issue 明显是重复的，请将新 issue 标记为“Duplicate”，并附带原始 issue 的链接关闭该 issue。请务必仍然感谢报告者，并鼓励他们在原始 issue 中发表意见，也许可以尝试修复它。

    如果新 issue 提供了相关信息，例如更好或略有不同的示例，请将其作为评论或对原始帖子的编辑添加到原始 issue 中。

  4. issue 是否最小且可复现?

    对于错误报告，我们要求报告者提供一个最小的可复现示例。请参阅https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports获取详细解释。如果示例不可复现，或者明显不最小化，请随时询问报告者是否可以提供示例或简化已提供的示例。请承认编写最小可复现示例是一项艰苦的工作。如果报告者遇到困难，您可以尝试自己编写一个，我们将编辑原始帖子以包含它。

    如果无法提供可复现示例，请添加“Needs info”标签。

    如果提供了可复现示例，但您发现可以简化，请使用您更简单的可复现示例编辑原始帖子。

    确保 issue 在 main 分支上存在，并在完成所有步骤之前保留“Needs Triage”标签。一旦您验证了它在 main 分支上存在，请在 issue 中添加评论，以便其他人知道它已被确认。

  5. 这是明确定义的功能请求吗？

    通常，pandas 倾向于在 issue 中讨论和设计新功能，然后再创建 pull request。鼓励提交者包含新功能的拟议 API。让他们编写完整的文档字符串是确定具体细节的好方法。

    将新的功能请求标记为“Needs Discussion”，因为在决定该提案是否属于 pandas 的范围之前，我们需要多个 pandas 维护者进行讨论。

  6. 这是使用问题吗？

    我们倾向于在 StackOverflow 上使用 pandas 标签提问使用问题。https://stackoverflow.com/questions/tagged/pandas

    如果容易回答，请随时链接到相关文档部分，告知他们将来此类问题应在 StackOverflow 上提问，然后关闭 issue。

  7. 我应该添加哪些标签和里程碑？

    应用相关的标签。这有点像一门艺术，需要经验。查看类似的 issue，了解如何进行标记。

    如果 issue 定义明确且修复看起来相对直接，请将 issue 标记为“Good first issue”。

    完成上述步骤后，请务必移除“needs triage”标签。

调查回归问题#

回归问题是意外破坏先前正常工作的代码的错误。调查回归问题的常用方法是使用 git bisect，它能找到引入该错误的第一个提交。

例如：用户报告称 pd.Series([1, 1]).sum() 在 pandas 1.5.0 版本中返回 3，而在 1.4.0 版本中返回 2。开始时，在您的 pandas 目录中创建一个文件 t.py，其中包含

import pandas as pd
assert pd.Series([1, 1]).sum() == 2

然后运行

git bisect start
git bisect good v1.4.0
git bisect bad v1.5.0
git bisect run bash -c "python setup.py build_ext -j 4; python t.py"

这会找到改变该行为的第一个提交。每一步都需要重新构建 C 扩展，因此搜索可能需要一些时间。

退出 bisect 并重建当前版本

git bisect reset
python setup.py build_ext -j 4

在相应的 issue 下报告您的发现，并 @ 提交作者以获取他们的意见。

注意

在上面的 bisect run 命令中，如果 t.py 以 0 退出，则认为提交是好的，否则是坏的。当抛出异常是期望的行为时，请将代码包装在适当的 try/except 语句中。有关更多示例，请参见 GH 35685。

关闭 issue#

这里要小心：许多人将关闭 issue 解读为我们说对话结束了。如果确定该行为不是 bug，或者该功能超出范围，通常最好给报告者一些时间回复或自行关闭他们的 issue。不过，有时报告者会消失，对话结束后我们会关闭 issue。如果您认为某个 issue 应该关闭但不完全确定，请应用“closing candidate”标签并等待其他维护者查看。

审查 pull request#

任何人都可以审查 pull request：普通贡献者、分流者或核心团队成员。但只有核心团队成员可以在 pull request 准备就绪时合并它们。

以下是在审查 pull request 时需要检查的一些事项。

  • 测试应放在合理的位置：与密切相关的测试放在同一个文件中。

  • 新的公共 API 应包含在 doc/source/reference/ 中的某个位置。

  • 新的/更改的 API 应在文档字符串中使用 versionadded 或 versionchanged 指令。

  • 面向用户的更改应在适当的文件中有 whatsnew 条目。

  • 回归测试应引用原始 GitHub issue 号，例如 # GH-1234。

  • pull request 应被标记并分配适当的里程碑（回归修复和小型错误修复分配到下一个补丁版本里程碑，否则分配到下一个次要版本里程碑）

  • 更改应符合我们的版本策略。

回移植#

pandas 支持点版本发布（例如 1.4.3），其目标是

  1. 修复在第一个次要版本发布中引入的新功能中的 bug。

  • 例如，如果在 1.4 中添加了一个新功能并包含 bug，则可以在 1.4.3 中应用修复。

  1. 修复在之前的几个次要版本中曾经正常工作的 bug。核心团队成员之间应对是否适合进行回移植达成一致。

  • 例如，如果一个功能在 1.2 中正常工作，但在 1.3 之后停止工作，则可以在 1.4.3 中应用修复。

由于 pandas 的次要版本发布基于 GitHub 分支（例如 1.4 的点版本发布基于 1.4.x 分支），因此“回移植”意味着将 pull request 修复合并到 main 分支以及与下一个点版本发布相关的正确次要分支。

默认情况下，如果在 GitHub 界面中将 pull request 分配给下一个点版本里程碑，一旦 pull request 合并，回移植过程应由 @meeseeksdev 机器人自动完成。将创建一个新的 pull request，将该 pull request 回移植到正确的版本分支。有时由于合并冲突，需要手动创建 pull request 来解决代码冲突。

如果机器人没有自动开始回移植过程，您也可以在合并的 pull request 中编写 GitHub 评论来触发回移植

@meeseeksdev backport version-branch

这将触发一个工作流，将给定更改回移植到分支（例如 @meeseeksdev backport 1.4.x）

清理旧 issue#

pandas 中的每个未解决 issue 都有成本。未解决 issue 会使查找重复项变得更加困难，并且难以了解在 pandas 中需要做什么。话虽如此，关闭 issue 本身并不是目标。我们的目标是让 pandas 尽可能地好，这最好通过确保我们未解决 issue 的质量来完成。

偶尔，bug 已修复，但在 pull request 中没有链接到相应的 issue。在这种情况下，请评论“这已修复，但可以添加测试。”并将 issue 标记为“Good First Issue”和“Needs Test”。

如果较旧的 issue 没有遵循我们的 issue 模板，请编辑原始帖子以包含最小示例、实际输出和预期输出。issue 报告的一致性非常有价值。

如果较旧的 issue 缺乏可复现示例，请将其标记为“Needs Info”并要求他们提供一个（如果可能，也可以自己编写）。如果合理的时间内没有提供，请根据关闭 issue中的策略将其关闭。

清理旧 pull request#

偶尔，贡献者无法完成 pull request。如果在上次要求更改的审查以来已经过了一段时间（例如两周），请温和地询问他们是否仍有兴趣继续工作。如果又过了大约两周没有回复，请感谢他们的工作，然后可以选择

  • 关闭 pull request；

  • 推送至贡献者的分支以帮助完成他们的工作（如果您是 pandas-core 的一部分）。这有助于推动重要的 PR 完成，或者修复小的合并冲突。

如果关闭 pull request，请在原始 issue 中评论“有一个停滞的 PR #1234 可能有帮助。”，如果该 PR 相对接近于被接受，可以将其标记为“Good first issue”。

成为 pandas 维护者#

完整的流程在我们的治理文档中有所概述。总而言之，我们乐于将分流权限授予任何通过在 issue 追踪器上提供帮助来表现出兴趣的人。

添加维护者所需步骤如下

  1. 联系贡献者并询问其加入的兴趣。

  2. 如果接受邀请，将贡献者添加到相应的GitHub Team。

  • pandas-core 适用于核心团队成员

  • pandas-triage 适用于 pandas 分流成员

如果添加到 pandas-core，还需要另外两个步骤

  1. 将贡献者添加到 pandas Google 群组。

  2. 创建一个 pull request，将贡献者的 GitHub 用户名添加到 pandas-dev/pandas/web/pandas/config.yml。

当前核心团队成员列表位于 pandas-dev/pandas

合并 pull request#

只有核心团队成员可以合并 pull request。我们有一些指导原则。

  1. 通常情况下，未经批准您不应自行合并自己的 pull request。例外情况包括修复 CI 的小型更改（例如固定包版本）。如果您对更改非常有信心，经其他核心团队成员批准后自行合并是可以的。

  2. 您不应合并仍在积极讨论的 pull request，或收到任何核心维护者投 -1 票的 pull request。pandas 采用共识机制运作。

  3. 对于较大的更改，最好至少获得两名核心团队成员的 +1 投票。

除了关闭 issue中列出的事项外，您还应验证 pull request 是否已分配正确的里程碑。

合并到补丁版本里程碑的 pull request 通常会由我们的机器人回移植。请验证机器人是否注意到了合并（它通常会在一分钟内留下评论）。如果需要手动回移植，请进行操作，并在手动完成后移除“Needs backport”标签。如果您在打标签前忘记分配里程碑，可以使用以下命令请求机器人进行回移植

@Meeseeksdev backport <branch>

基准测试机器#

团队目前拥有专用硬件，用于托管 pandas ASV 性能基准测试的网站。结果发布在 https://asv-runner.github.io/asv-collection/pandas/

配置#

该机器可以使用 tomaugspurger/asv-runner 中的 Ansible 脚本进行配置。

发布#

结果发布到另一个 GitHub 仓库 tomaugspurger/asv-collection。最后，我们在文档服务器上有一个 cron 作业，从 tomaugspurger/asv-collection 拉取数据，以便从 /speed 提供服务。请联系 Tom 或 Joris 获取 webserver 访问权限。

调试#

基准测试由 Airflow 调度。它有一个仪表板用于查看和调试结果。您需要设置 SSH 隧道才能查看它们

ssh -L 8080:localhost:8080 pandas@panda.likescandy.com

发布流程#

发布流程将 pandas 的快照（一个 git commit）以特定版本号提供给用户。发布后，新的 pandas 版本将可在以下位置获取

发布新版本 pandas 的流程将在下一节详细介绍。

说明中包含 <version>，需要替换为待发布的版本号（例如 1.5.2）。还有待发布的分支 <branch>，这取决于待发布的版本是新版本的发布候选版本还是其他任何版本。发布候选版本从 main 发布，而其他版本从其分支发布（例如 1.5.x）。

先决条件#

为了能够发布新的 pandas 版本，需要以下权限

  • 对 pandas 和 pandas-feedstock 仓库的合并权限。对于后者，请开启一个 PR 将您的 GitHub 用户名添加到 conda-forge 配方中。

  • 将新标签推送到 pandas 仓库中 main 分支的权限。

  • 对 PyPI 的写入权限.

  • 访问我们的网站/文档服务器的权限。与基础设施委员会共享您的公钥，以便将其添加到主服务器用户的 authorized_keys 文件中。

  • 访问社交媒体账户的权限，用于发布公告。

预发布#

  1. 与核心团队就以下主题达成一致

    • 发布日期（主要/次要版本通常每 6 个月发布一次，补丁版本每月发布一次，直到 x.x.5 版本，紧接在下一个主要/次要版本之前）

    • 阻碍项（必须包含在发布中的 issue 和 PR）

    • 当前发布版本之后的下一个版本

  2. 更新和清理待发布版本的发布说明，包括

    • 设定最终发布日期

    • 移除任何未使用的项目符号

    • 确保没有格式问题、拼写错误等。

  3. 确保待发布分支的最后一个提交的 CI（持续集成）通过。

  4. 如果不是发布候选版本，请确保所有回移植到待发布分支的 pull request 都已合并。

  5. 为当前发布版本之后的版本创建新的 issue 和里程碑。如果发布的是发布候选版本，我们通常会为下一个主要/次要版本和下一个补丁版本创建 issue 和里程碑。在补丁版本的里程碑中，我们添加描述 on-merge: backport to <branch>，以便标记的 PR 由我们的机器人自动回移植到发布分支。

  6. 将待发布里程碑中的所有 issue 和 PR 的里程碑更改为下一个里程碑。

发布#

  1. 在待发布分支的最后一个提交中创建一个空提交和一个标签

    git checkout <branch>
git pull --ff-only upstream <branch>
git clean -xdf
git commit --allow-empty --author="Pandas Development Team <[email protected]>" -m "RLS: <version>"
git tag -a v<version> -m "Version <version>"  # NOTE that the tag is v1.5.2 with "v" not 1.5.2
git push upstream <branch> --follow-tags

新版本的文档将通过 CI 中的文档作业自动构建和发布，该作业将在标签推送时触发。

  1. 只有当发布是发布候选版本时，我们才需要在创建标签后立即为其创建一个新分支。例如，如果我们发布 pandas 1.4.0rc0，我们希望创建 1.4.x 分支以将提交回移植到 1.4 版本。同时创建标签以标记 1.5.0 版本开发的开始（假设它是下一个版本）

    git checkout -b 1.4.x
git push upstream 1.4.x
git checkout main
git commit --allow-empty -m "Start 1.5.0"
git tag -a v1.5.0.dev0 -m "DEV: Start 1.5.0"
git push upstream main --follow-tags

  2. 从轮子暂存区下载源分发包和轮子。请务必确保没有缺少轮子（例如由于构建失败）。

    运行 scripts/download_wheels.sh，并指定您要下载轮子/sdist 的版本，即可完成。该脚本会在您的 pandas 克隆仓库内创建一个 dist 文件夹，并将下载的轮子和 sdist 放在其中

    scripts/download_wheels.sh <VERSION>

  3. 创建新的 GitHub 发布

    • 标签：<version>

    • 标题：Pandas <version>

    • 描述：复制同类型（发布候选版本、主要/次要版本或补丁版本）上次发布的描述

    • 文件：刚刚生成的 pandas-<version>.tar.gz 源分发包

    • 设为预发布：仅针对发布候选版本勾选

    • 设为最新发布：保持勾选，除非正在发布旧版本的补丁版本（例如在 1.5 已发布后发布 1.4.5）

  4. 上传轮子到 PyPI

    twine upload pandas/dist/pandas-<version>*.{whl,tar.gz} --skip-existing

  5. GitHub 发布将在几小时后触发一个自动化的 conda-forge PR。（如果您不想等待，可以开启一个标题为 @conda-forge-admin, please update version 的 issue 来触发机器人。）一旦 CI 通过，即可合并该 PR，它将生成 conda-forge 包。

    如果需要手动创建 PR，通常需要更改 version、sha256 和 build 字段。如果配方中自上次发布以来有其他更改，这些更改应可在 ci/meta.yaml 中找到。

发布后#

  1. 通过登录我们的 web 服务器，更新指向稳定文档的符号链接，编辑 /var/www/html/pandas-docs/stable，对于主要和次要版本，使其指向 version/<latest-version>；对于补丁版本，使其指向 version/<minor> 到 version/<patch>。具体说明如下（请将示例版本号替换为您正在发布的版本的相应版本号）

    • 登录服务器并使用正确的用户。

    • cd /var/www/html/pandas-docs/

    • ln -sfn version/2.1 stable （适用于主要或次要版本）

    • ln -sfn version/2.0.3 version/2.0 （适用于补丁版本）

  2. 如果发布主要或次要版本，请在我们的源代码中开启一个 PR 更新 web/pandas/versions.json，以便在文档下拉菜单中显示所需的版本。

  3. 关闭已发布版本的里程碑和 issue。

  4. 为下一个版本创建一个新的 issue，并附上估计的发布日期。

  5. 开启一个 PR，包含下一个版本的发布说明占位符。例如，请参见1.5.3 版本的 PR。请注意，使用的模板取决于它是主要、次要还是补丁版本。

  6. 在官方渠道宣布新版本发布（参考之前的公告）

    • pandas-dev 和 pydata 邮件列表

    • Twitter, Mastodon, Telegram 和 LinkedIn

  7. 更新本发布说明，修正任何不正确之处，并更新自上次发布以来的任何更改。