熊猫维护# 本指南适用于 pandas 的维护者。对于希望了解 pandas 开发过程以及成为维护者所需的步骤的贡献者来说，这可能也会很有趣。 主要贡献指南可在Contributing to pandas中找到。 角色# pandas 使用两个级别的权限：分类和核心团队成员。 分类成员可以标记和关闭问题以及拉取请求。 核心团队成员可以标记和关闭问题和拉取请求，并且可以合并拉取请求。 GitHub 发布了完整的权限列表。 任务＃ pandas 在很大程度上是一个志愿者项目，因此这些任务不应被理解为分类和维护人员的“期望”。相反，它们是对维护者意味着什么的一般描述。 对新提交的问题进行分类（请参阅问题分类） 审查新打开的拉取请求 响应现有问题和拉取请求的更新 推动对停滞问题和拉取请求的讨论和决策 提供API设计问题的经验/智慧，确保一致性和可维护性 项目组织（运行/参加开发者会议，代表 pandas） https://matthewrocklin.com/blog/2019/05/18/maintainer可能是有趣的背景阅读。 问题分类# 分类是解决社区报告问题的重要第一步，即使是部分贡献也是帮助维护熊猫的好方法。仅在完成以下所有步骤后才删除“需要分类”标签。 以下是对新打开的问题进行分类的典型工作流程。 感谢记者提出问题 问题跟踪器是许多人与 pandas 项目本身的第一次交互，而不仅仅是使用库。因此，我们希望这是一次温馨、愉快的体验。 是否提供了必要的信息？ 理想情况下，记者会填写问题模板，但很多人不会。如果缺少重要信息（例如他们使用的 pandas 版本），请随时询问并将问题标记为“需要信息”。该报告应遵循错误报告和增强请求中的指导原则。如果他们不遵循模板，您可能需要链接到该链接。 确保标题准确反映问题。如果不清楚的话自行编辑。 这是一个重复的问题吗？ 我们有许多悬而未决的问题。如果新问题明显重复，请将新问题标记为“重复”，并通过原始问题的链接关闭该问题。确保仍然感谢记者，并鼓励他们参与最初的问题，也许尝试解决它。 如果新问题提供了相关信息，例如更好或略有不同的示例，请将其作为评论或对原始帖子的编辑添加到原始问题中。 问题是否最小且可重现？ 对于错误报告，我们要求报告者提供一个最小的可重现示例。 有关详细解释，请参阅https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports 。如果该示例不可重现，或者显然不是 最小的，请随时询问记者是否可以提供示例或简化所提供的示例。请承认编写最少的可重现示例是一项艰苦的工作。如果记者遇到困难，您可以尝试自己写一篇，我们将编辑原始帖子以将其包含在内。 如果无法提供可重现的示例，请添加“需要信息”标签。 如果提供了可重现的示例，但您看到了简化，请使用更简单的可重现示例编辑原始帖子。 确保问题存在于主分支上，并且具有“需要分类”标签，直到完成所有步骤。一旦您确认该问题存在于主分支上，请添加对该问题的评论，以便其他人知道该问题已得到确认。 这是一个明确定义的功能请求吗？ 一般来说，pandas 更喜欢在发出 pull request 之前在问题中讨论和设计新功能。鼓励提交者为新功能添加建议的 API。让他们编写完整的文档字符串是确定细节的好方法。 用“需要讨论”标记新功能请求，因为在决定该提案是否在 pandas 范围内之前，我们需要几个 pandas 维护者进行讨论。 这是一个使用问题吗？ 我们更喜欢在 StackOverflow 上使用 pandas 标签询问使用问题。https://stackoverflow.com/questions/tagged/pandas 如果很容易回答，请随意链接到相关文档部分，让他们知道将来此类问题应该出现在 StackOverflow 上，并关闭该问题。 我应该添加哪些标签和里程碑？ 贴上相关标签。这是一门艺术，并且需要经验。查看类似的问题以了解事物是如何标记的。 如果问题定义明确并且修复看起来相对简单，则将该问题标记为“良好的第一个问题”。 完成上述操作后，请务必删除“需求分类”标签。 研究回归# 回归是无意中破坏之前工作代码的错误。研究回归的常见方法是使用 git bisect，它会找到引入错误的第一个提交。 例如：用户报告 以 pandas 版本返回，而以它返回的版本返回。首先，在 pandas 目录中创建一个文件，其中包含pd.Series([1, 1]).sum()31.5.01.4.02t.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 在相应问题下报告您的发现，并 ping 提交作者以获取他们的意见。 笔记 在上面的命令中，如果退出则认为提交是好的，否则认为提交是坏的。当引发异常是所需的行为时，请将代码包装在适当的语句中。更多示例请参见GH 35685 。bisect runt.py0try/except 结束问题# 这里要小心：许多人将结束问题理解为我们说对话结束了。如果确定该行为不是错误，或者该功能超出了范围，通常最好给报告者一些时间来回应或自行关闭他们的问题。有时记者会离开，我们会在谈话结束后关闭该问题。如果您认为某个问题应该关闭但不完全确定，请应用“关闭候选人”标签并等待其他维护者查看。 审查拉取请求# 任何人都可以审查拉取请求：常规贡献者、分类人员或核心团队成员。但只有核心团队成员准备好后才能合并拉取请求。 以下是审查拉取请求时需要检查的一些事项。 测试应该位于合理的位置：与密切相关的测试位于同一文件中。 新的公共 API 应该包含在doc/source/reference/. 新的/更改的 API 应使用文档字符串中的versionadded或指令。versionchanged 面向用户的更改应该在适当的文件中包含新内容。 回归测试应引用原始 GitHub 问题号，例如.# GH-1234 拉取请求应该被标记并分配适当的里程碑（回归修复和小错误修复的下一个补丁版本，否则下一个小里程碑） 更改应符合我们的版本政策。 向后移植# pandas 支持点发布（例如1.4.3），旨在： 修复第一个小版本发布中引入的新功能中的错误。 例如，如果添加了新功能1.4并包含错误，则可以应用修复1.4.3 修复以前在几个小版本中存在的错误。核心团队成员之间应该就向后移植是适当的达成一致。 例如，如果某个功能在 中工作1.2并从 后停止工作1.3，则可以在 中应用修复1.4.3。 由于 pandas 次要版本基于 GitHub 分支（例如，点发布1.4基于1.4.x分支），因此“向后移植”意味着将拉取请求修复合并到main分支以及与下一个点版本关联的正确次要分支。 默认情况下，如果将拉取请求分配给 GitHub 界面中的下一个发布里程碑，@meeseeksdev则在合并拉取请求后，机器人应自动进行向后移植过程。将发出新的拉取请求，将拉取请求向后移植到正确的版本分支。有时由于合并冲突，需要发出手动拉取请求来解决代码冲突。 如果机器人没有自动启动反向移植过程，您还可以在合并的拉取请求中编写 GitHub 注释来触发反向移植： @meeseeksdev backport version-branch 这将触发一个工作流程，该工作流程会将给定的更改向后移植到分支（例如@meeseeksdev向后移植1.4.x） 清理旧问题# pandas 中的每个未解决问题都会产生成本。开放性问题使得查找重复项变得更加困难，并且使得了解 pandas 中需要做什么变得更加困难。也就是说，解决问题本身并不是一个目标。我们的目标是让 pandas 成为最好的，而最好的方法是确保我们的开放问题的质量很高。 有时，错误已修复，但问题未在拉取请求中链接到。在这些情况下，请评论“此问题已修复，但可以进行测试。”并将问题标记为“Good First Issue”和“Need Test”。 如果旧问题不遵循我们的问题模板，请编辑原始帖子以包含最小示例、实际输出和预期输出。问题报告的一致性很有价值。 如果较旧的问题缺乏可重现的示例，请将其标记为“需要信息”并要求他们提供一个（或者如果可能的话自己写一个）。如果未尽快提供，请根据关闭问题中的政策将其关闭。 清理旧的拉取请求# 有时，贡献者无法完成拉取请求。如果自上次审核请求更改以来已经过go了一段时间（例如两周），请温和地询问他们是否仍然有兴趣从事此工作。如果又过了两周左右仍没有回复，请感谢他们的工作，然后： 关闭拉取请求； 推送到贡献者的分支，将他们的工作推过终点线（如果您是 的一部分pandas-core）。这有助于推动重要的 PR 越过界限，或者修复小的合并冲突。 如果关闭拉取请求，请对原始问题发表评论“#1234 有一个停滞的 PR 可能会有所帮助。”，如果 PR 相对接近被接受，则可以将该问题标记为“良好的第一期”。 成为熊猫维护者# 我们的治理文件概述了完整的流程。总之，我们很高兴向任何通过对问题跟踪器提供帮助而表现出兴趣的人授予分类权限。 添加维护者所需的步骤是： 联系贡献者并询问他们是否有兴趣加入。 如果接受邀请，请将贡献者添加到相应的GitHub 团队。 pandas-core适用于核心团队成员 pandas-triage适用于 Pandas 分类会员 如果添加到pandas-core，还有两个额外步骤： 将贡献者添加到 pandas Google 群组。 创建拉取请求以将贡献者的 GitHub 句柄添加到pandas-dev/pandas/web/pandas/config.yml. 当前的核心团队成员列表位于 pandas-dev/pandas 合并拉取请求# 只有核心团队成员才能合并拉取请求。我们有一些指导方针。 未经批准，您通常不应自行合并自己的拉取请求。例外情况包括修复 CI 的小更改（例如固定包版本）。如果您对变革非常有信心，那么在其他核心团队成员的批准下进行自我合并是可以的。 您不应合并具有活跃讨论的拉取请求，或具有-1核心维护者投票的拉取请求。 pandas 通过共识运作。 对于较大的更改，最好获得至少两名核心团队成员的+1。 除了结束问题中列出的项目之外，您还应该验证是否为拉取请求分配了正确的里程碑。 与补丁发布里程碑合并的拉取请求通常会由我们的机器人向后移植。验证机器人是否注意到合并（通常会在一分钟内留下评论）。如果需要手动向后移植，请执行此操作，并在手动完成后删除“需要向后移植”标签。如果您忘记在标记之前分配里程碑，您可以请求机器人通过以下方式向后移植它： @Meeseeksdev backport <branch> 基准机# 该团队目前拥有专用硬件来托管 pandas 的 ASV 性能基准网站。结果发布到https://asv-runner.github.io/asv-collection/pandas/ 配置＃ 可以使用tomaugspurger/asv-runner中的Ansible playbook配置机器。 发布# 结果发布到另一个 GitHub 存储库tomaugspurger/asv-collection。最后，我们的文档服务器上有一个 cron 作业，可以从tomaugspurger/asv-collection中提取，以便从/speed.向 Tom 或 Joris 请求访问网络服务器。 调试# 基准测试由 Airflow 安排。它有一个用于查看和调试结果的仪表板。您需要设置 SSH 隧道才能查看它们 ssh -L 8080:localhost:8080 pandas@panda.likescandy.com 发布流程# 发布过程使具有特定版本号的用户可以使用 pandas 的快照（git 提交）。发布后，新的 pandas 版本将在以下位置提供： 带有新标签的Git 存储库 GitHub 版本中的源代码分发 PyPI中的 Pip 包 conda-forge中的 Conda/Mamba 包 下一节将详细介绍发布新版本 pandas 的过程。 说明中包含<version>需要替换为要发布的版本的内容（例如1.5.2）。还有要发布的分支<branch>，这取决于正在发布的版本是新版本还是任何其他版本的候选版本。候选版本从 发布main，而其他版本则从其分支发布（例如1.5.x）。 先决条件# 为了能够发布新的 pandas 版本，需要以下权限： 合并pandas和 pandas-feedstock存储库的权利。对于后者，打开一个 PR，将您的 GitHub 用户名添加到 conda-forge 配方中。 推送到mainpandas 存储库、推送新标签的权限。 对 PyPI 的写入权限。 访问我们的网站/文档服务器。与基础设施委员会共享您的公钥，以将其添加到authorized_keys主服务器用户的文件中。 访问社交媒体帐户，发布公告。 预发布# 与核心团队就以下主题达成一致： 发布日期（主要/次要版本通常每 6 个月发布一次，补丁每月发布一次，直到 xx5，就在下一个主要/次要版本之前） 阻止者（必须成为版本一部分的问题和 PR） 发布后的下一个版本 更新并清理要发布版本的发行说明，包括： 设定最终发布日期 删除所有未使用的项目符号点 确保没有格式问题、拼写错误等。 确保正在发布的分支的最后一次提交的 CI 为绿色。 如果不是候选版本，请确保合并所有向后移植到正在发布的分支的拉取请求。 在发布版本后，为该版本创建一个新的问题和里程碑。如果该版本是候选版本，我们通常希望为下一个主要/次要版本以及下一个补丁版本创建问题和里程碑。在补丁发布的里程碑中，我们添加了描述，因此标记的 PR 会被我们的机器人自动反向移植到发布分支。on-merge: backport to <branch> 将正在发布的里程碑中的所有问题和 PR 的里程碑更改为下一个里程碑。 发布＃ 在要发布的分支的最后一次提交中创建一个空提交和一个标记： 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 中的文档作业自动构建和发布，推送标签时将触发该作业。 仅当该版本是候选版本时，我们才想在创建标签后立即为其创建一个新分支。例如，如果我们要发布 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 从wheel暂存区下载源发行版和wheels 。小心确保没有轮子丢失（例如由于构建失败）。 使用您想要下载wheels/sdist 的版本运行scripts/download_wheels.sh 应该可以解决问题。该脚本将dist在您的 pandas 克隆中创建一个文件夹，并将下载的轮子和 sdist 放在那里： scripts/download_wheels.sh <VERSION> 创建一个新的 GitHub 版本： 标签：<version> 标题：Pandas <version> 描述：复制同类最后一个版本的描述（候选版本、主要/次要版本或补丁版本） 文件：pandas-<version>.tar.gz刚刚生成的源分发 设置为预发布：仅检查候选版本 设置为最新版本：保留选中状态，除非发布旧版本的补丁版本（例如，在 1.5 发布后发布 1.4.5） 将轮子上传到 PyPI： twine upload pandas/dist/pandas-<version>*.{whl,tar.gz} --skip-existing GitHub 版本将在几个小时后触发 自动 conda-forge PR。 （如果您不想等待，可以打开一个标题为触发机器人的问题。）一旦 CI 变为绿色，就将其合并，它将生成 conda-forge 包。@conda-forge-admin, please update version 如果需要进行手动 PR，通常需要更改版本、sha256 和构建字段。如果自上次版本以来配方中的其他内容发生了更改，那么这些更改应该在ci/meta.yaml. 发布后# 通过登录我们的 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（用于补丁版本） 如果发布主要或次要版本，请在我们的源代码中打开 PR 进行更新 web/pandas/versions.json，以便在文档下拉菜单中获得所需的版本。 关闭已发布版本的里程碑和问题。 为下一个版本创建一个新问题，并注明预计的发布日期。 使用下一版本发行说明的占位符打开 PR。例如，请参阅1.5.3 的 PR。请注意，要使用的模板取决于它是主要版本、次要版本还是补丁版本。 在官方渠道发布新版本公告（参考之前的公告）： pandas-dev 和 pydata 邮件列表 Twitter、Mastodon、Telegram 和 LinkedIn 更新此版本说明以修复任何不正确的内容并更新自上次版本以来的任何更改。