pandas 维护#

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

主要贡献指南可在 为 pandas 贡献 中找到。

角色#

pandas 使用两个级别的权限：triaging（分类）和 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”（需要信息）。报告应遵循 Bug 报告和功能请求 中的指南。如果他们没有遵循模板，您可能想链接到该指南。

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

  3. 这是一个重复的 issue 吗？

    我们有很多开放的 issue。如果新 issue 明显是重复的，则将新 issue 标记为“Duplicate”（重复），并关闭该 issue，附上指向原始 issue 的链接。请务必仍然感谢报告者，鼓励他们参与到原始 issue 的讨论中，并尝试修复它。

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

  4. Issue 是否最小且可重现?

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

    如果无法提供可重现的示例，请添加“Needs info”（需要信息）标签。

    如果提供了可重现的示例，但您看到了简化的可能性，请用您更简化的可重现示例编辑原始帖子。

    如果是回归报告，请发布 git bisect 运行的结果。有关更多信息，请参阅 调查回归 部分。

    确保 issue 存在于主分支上，并且在所有步骤完成后，保留“Needs Triage”（需要分类）标签。在 issue 上添加评论，一旦您确认它存在于主分支上，以便其他人知道它已被确认。

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

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

    将新功能请求标记为“Needs Discussion”（需要讨论），因为我们需要多位 pandas 维护者的讨论，然后才能决定该提案是否在 pandas 的范围内。

  6. 这是一个使用问题吗？

    我们更希望在 StackOverflow 上使用 pandas 标签来提问。 https://stackoverflow.com/questions/tagged/pandas

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

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

    应用相关标签。这有点像一门艺术，需要经验。查看类似的 issue 以了解事物的标记方式。

    如果 issue 定义清晰，并且修复看起来相对简单，则将 issue 标记为“Good first issue”（一个好的起点）。

    如果 issue 是回归报告，请添加“Regression”（回归）标签和下一个补丁版本里程碑。

    完成以上步骤后，请确保删除“Needs Triage”（需要分类）标签。

调查回归#

回归是指无意中破坏了先前工作代码的 bug。调查回归的常用方法是使用 git bisect，它会找到引入 bug 的第一个 commit。

例如：一个用户报告 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 -m pip install -ve . --no-build-isolation -Ceditable-verbose=true; python t.py"

这将找到更改行为的第一个 commit。C 扩展在每一步都必须重新构建，因此搜索可能需要一段时间。

退出 bisect 并重新构建当前版本

git bisect reset
python -m pip install -ve . --no-build-isolation -Ceditable-verbose=true

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

注意

在上面的 bisect run 命令中，如果 t.py 退出代码为 0，则认为 commit 是好的，否则是坏的。当引发异常是期望的行为时，请将代码包装在适当的 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 应在 docstring 中使用 versionadded 或 versionchanged 指令。

  • 面向用户的更改应在相应文件中有一个 whatsnew（更新日志）。

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

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

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

回溯移植#

pandas 支持点发布（例如 1.4.3），旨在

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

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

  2. 修复在几个次要版本之前曾正常工作的 bug。核心团队成员应就回溯移植的适当性达成一致。

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

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

默认情况下，如果 pull request 被分配到 GitHub 界面中的下一个点发布里程碑，则 @meeseeksdev 机器人将在 pull request 合并后自动执行回溯移植过程。将创建一个新的 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。在这种情况下，请评论“This has been fixed, but could use a test.”（已修复，但需要一个测试），并将 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 上评论“There’s a stalled PR at #1234 that may be helpful.”（有一个停滞的 PR #1234 可能有帮助），并且如果 PR 已经接近被接受，可以将其标记为“Good first issue”（一个好的起点）。

成为 pandas 维护者#

完整的流程已在我们的 治理文件中 概述。总而言之，我们很乐意授予对 issue 跟踪器表现出兴趣并通过提供帮助来做出贡献的任何人以分类权限。

添加维护者所需的步骤是

  1. 联系贡献者，询问他们是否有加入的意愿。

  2. 如果接受邀请，请将贡献者添加到适当的 GitHub 团队。

    • 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 的快照（一个 git commit）可供用户使用，并带有一个特定的版本号。发布后，新版本的 pandas 将在以下位置可用

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

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

先决条件#

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

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

  • 在 pandas 仓库中推送到 main 的权限，以推送新标签。

  • PyPI 的写入权限.

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

  • 访问社交媒体账号，以发布公告。

预发布#

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

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

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

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

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

    • 设定发布的最终日期

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

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

  3. 确保正在发布的分支的最后一个 commit 的 CI 状态为绿色。

  4. 如果不是发布候选版，请确保所有回溯移植到正在发布分支的 pull request 都已合并，并且没有已合并的 pull request 缺少回溯移植（为此请检查 [“Still Needs Manual Backport”](pandas-dev/pandas) 标签）。

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

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

发布#

  1. 在要发布的最后一个 commit 上创建一个空 commit 和一个标签

    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 中的 docs 作业自动构建和发布，该作业将在推送标签时触发。

  1. 仅当发布的是发布候选版时，我们才希望立即创建一个新分支，紧随其后。例如，如果我们正在发布 pandas 1.4.0rc0，我们希望创建一个 1.4.x 分支以回溯移植 commits 到 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. 从 wheel 暂存区下载源分发和 wheels。请注意确保没有遗漏任何 wheels（例如，由于构建失败）。

  3. 创建一个 新的 GitHub release

    • 标签： <version>

    • 标题： pandas <version>

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

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

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

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

  4. 验证 wheels 是否通过 **Trusted Publishing** 由 GitHub Actions 自动上传，当 GitHub *Release* 发布时。请勿手动运行 twine upload。

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

    如果需要手动 PR，通常需要更改的是 version、sha256 和 build 字段。如果 recipe 中的任何其他内容自上次发布以来发生了变化，则这些更改应在 ci/meta.yaml 中提供。

发布后#

  1. 更新指向稳定文档的符号链接，方法是登录到我们的 Web 服务器，并将 /var/www/html/pandas-docs/stable 指向 version/<X.Y>（对于主/次要版本），或将 version/<X.Y> 指向 version/<patch>（对于补丁版本）。确切的说明如下（请将示例版本号替换为与您要发布的版本相对应的版本号）

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

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

    • 对于主版本或次要版本（假设 /version/2.1.0/ 文档已上传到服务器）

      • 创建新的 X.Y 符号链接指向 X.Y.Z： cd version; ln -sfn 2.1.0 2.1

      • 更新 stable 符号链接以指向 X.Y： ln -sfn version/2.1 stable

    • 对于补丁版本（假设 /version/2.1.3/ 文档已上传到服务器）

      • 将 X.Y 符号链接更新到新的 X.Y.Z 补丁版本： cd version; ln -sfn 2.1.3 2.1

      • （stable 符号链接应该已经指向正确的 X.Y 版本）

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

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

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

  5. 打开一个 PR，其中包含下一个版本的 release notes 的占位符。例如，请参阅 1.5.3 的 PR。请注意，使用的模板取决于它是主版本、次要版本还是补丁版本。

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

    • pandas-dev 和 pydata 邮件列表

    • X、Mastodon、Telegram 和 LinkedIn

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