贡献 pandas#

欢迎所有贡献，包括 bug 报告、bug 修复、文档改进、增强功能和想法。

Bug 报告和增强请求#

Bug 报告和增强请求是使 pandas 更加稳定的重要组成部分，并通过 Github issues 进行管理。报告问题或请求时，请选择适当的类别并完整填写问题表单，以确保其他人以及核心开发团队能完全理解问题的范围。

该问题将随后显示给 pandas 社区，并开放接受其他人的评论/想法。

寻找可以贡献的问题#

如果你是 pandas 或开源开发的新手，我们建议你在 GitHub“issues”选项卡中搜索你感兴趣的问题。标有 Docs 和 good first issue 且未分配的问题通常适合新贡献者。

一旦你找到一个有趣的问题，最好将该问题分配给自己，这样就不会有人重复你的工作。在 Github 问题上，评论中输入精确文本 take 即可自动将问题分配给你（这只需几秒钟，可能需要刷新页面才能看到）。

如果由于任何原因你无法继续处理该问题，请取消分配该问题，以便其他人知道它再次可用。你可以查看已分配问题的列表，因为人们可能不再处理它们了。如果你想处理一个已经分配的问题，请随时友好地询问当前的分配者是否可以接手（请至少等待一周的非活动期，然后再考虑该问题的工作已中止）。

我们有几个贡献者社区沟通渠道，欢迎你加入并在摸索过程中提问。其中包括面向新贡献者的定期会议、开发者会议、开发者邮件列表以及贡献者社区的 Slack 频道。所有 pandas 贡献者都欢迎加入这些空间，他们可以在那里相互联系。即使是长期与我们在一起的维护者，刚开始时也和你一样，他们很乐意欢迎你并支持你了解我们的工作方式和资源位置。请查看下一节了解更多信息。

提交拉取请求#

版本控制、Git 和 GitHub#

pandas 托管在 GitHub 上，要做出贡献，你需要注册一个免费的 GitHub 账户。我们使用 Git 进行版本控制，允许多人在项目上协同工作。

如果你是 Git 新手，可以参考这些资源学习 Git。如果需要帮助，请随时联系贡献者社区

此外，本项目采用本文进一步描述的分支（forking）工作流程，贡献者通过该流程分支仓库，进行更改，然后创建拉取请求。因此，请务必阅读并遵循本指南中的所有说明。

如果你是第一次通过 GitHub 上的分支为项目做贡献，请参阅GitHub 的项目贡献文档。GitHub 提供了一个使用测试仓库的快速教程，这可能有助于你更熟悉分支仓库、克隆分支、创建特性分支、推送更改和发起拉取请求的操作。

以下是一些用于进一步了解 GitHub 上分支和拉取请求的有用资源

Git 入门#

GitHub 有关于安装 git、设置 SSH 密钥和配置 git 的说明。所有这些步骤都需要在你能够在本地仓库和 GitHub 之间无缝工作之前完成。

创建 pandas 的分支（fork）#

你需要一份自己的 pandas 副本（即分支）来处理代码。前往 pandas 项目页面并点击 Fork 按钮。请取消选中仅复制主分支的复选框，然后再选择 Create Fork。你将需要将你的分支克隆到你的机器上

git clone https://github.com/your-user-name/pandas.git pandas-yourname
cd pandas-yourname
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream

这将创建目录 pandas-yourname，并将你的仓库连接到上游（主项目） pandas 仓库。

注意

执行浅层克隆（使用 --depth==N，其中 N 大于或等于 1）可能会破坏一些测试和功能，例如 pd.show_versions()，因为版本号无法再计算。

创建特性分支#

你的本地 main 分支应始终反映 pandas 仓库的当前状态。首先确保它与主 pandas 仓库保持同步。

git checkout main
git pull upstream main --ff-only

然后，创建用于进行更改的特性分支。例如

git checkout -b shiny-new-feature

这将你的工作分支从 main 更改为 shiny-new-feature 分支。在此分支中，将所有更改限制在一个 bug 或特性上，以便清楚该分支为 pandas 带来了什么。你可以有许多特性分支，并使用 git checkout 命令在它们之间切换。

创建分支后，如果你想用 main 中的更改来更新特性分支，请查看关于更新 PR 的部分。

进行代码更改#

在修改任何代码之前，请确保你遵循贡献环境指南来设置合适的开发环境。

然后，在你进行了代码更改后，可以通过运行以下命令查看所有当前所做的更改。

git status

对于你打算修改或添加的文件，请运行。

git add path/to/file-to-be-added-or-changed.py

再次运行 git status 应该显示

On branch shiny-new-feature

     modified:   /relative/path/to/file-to-be-added-or-changed.py

最后，使用带有解释性信息的提交消息将你的更改提交到本地仓库

git commit -m "your commit message goes here"

推送你的更改#

当你希望你的更改在你的 GitHub 页面上公开显示时，请推送你的分支特性分支的提交

git push origin shiny-new-feature

这里的 origin 是你的 GitHub 远程仓库的默认名称。你可以查看远程仓库

git remote -v

如果你按照上述说明添加了上游仓库，你将看到类似以下内容

origin  [email protected]:yourname/pandas.git (fetch)
origin  [email protected]:yourname/pandas.git (push)
upstream        git://github.com/pandas-dev/pandas.git (fetch)
upstream        git://github.com/pandas-dev/pandas.git (push)

现在你的代码已在 GitHub 上，但它尚未成为 pandas 项目的一部分。为此，需要在 GitHub 上提交拉取请求。

发起拉取请求#

完成代码更改后，你的代码更改需要遵循pandas 贡献指南才能成功被接受。

如果一切看起来都好，你就可以发起拉取请求了。拉取请求是你本地仓库的代码供 GitHub 社区审查并合并到项目中以便在下个版本中出现的方式。要提交拉取请求

  1. 导航到你在 GitHub 上的仓库

  2. 点击 Compare & pull request（比较并拉取请求）按钮

  3. 然后你可以点击 Commits（提交）和 Files Changed（文件更改）来最后一次确认一切正常

  4. 撰写一个包含前缀的描述性标题。pandas 对标题前缀有一个约定。这里列出了一些常见前缀以及何时使用它们的一般准则

    • ENH: 增强功能，新功能

    • BUG: Bug 修复

    • DOC: 文档添加/更新

    • TST: 测试添加/更新

    • BLD: 构建过程/脚本更新

    • PERF: 性能改进

    • TYP: 类型注解

    • CLN: 代码清理

  5. 在 Preview Discussion（预览讨论）选项卡中填写你的更改描述

  6. 点击 Send Pull Request（发送拉取请求）。

该请求随后会发送给仓库维护者，他们将审查代码。

更新你的拉取请求#

根据你的拉取请求收到的审查意见，你可能需要对代码进行一些更改。你可以再次按照代码提交步骤来处理反馈并更新你的拉取请求。

同样重要的是，pandas main 分支中的更新应反映在你的拉取请求中。要用 pandas main 分支中的更改更新你的特性分支，请运行

git checkout shiny-new-feature
git fetch upstream
git merge upstream/main

如果没有冲突（或者可以自动解决），将打开一个带有默认提交消息的文件，你只需保存并退出该文件即可。

如果存在合并冲突，你需要解决这些冲突。例如，请参阅 https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ 获取关于如何执行此操作的解释。

解决冲突后，运行

  1. git add -u 来暂存你更新的所有文件；

  2. git commit 来完成合并。

注意

如果你在希望用 main 更新分支时有未提交的更改，你需要在更新之前 stash（暂存）它们（参见 stash 文档）。这会有效地保存你的更改，并且可以在更新后重新应用它们。

在本地更新特性分支后，你现在可以通过推送到 GitHub 上的分支来更新你的拉取请求

git push origin shiny-new-feature

任何 git push 操作都会自动用你分支的更改更新你的拉取请求，并重新启动持续集成检查。

更新开发环境#

定期使用 pandas main 分支的更新来更新你的本地 main 分支，并更新你的开发环境以反映开发过程中使用的各种软件包的任何更改，这一点很重要。

如果使用 mamba，运行

git checkout main
git fetch upstream
git merge upstream/main
mamba activate pandas-dev
mamba env update -f environment.yml --prune

如果使用 pip，执行

git checkout main
git fetch upstream
git merge upstream/main
# activate the virtual environment based on your platform
python -m pip install --upgrade -r requirements-dev.txt

成功发起拉取请求的提示#

如果你已经进入了发起拉取请求阶段，某个核心贡献者可能会查看。但请注意，负责审查所有贡献的人数有限，这通常可能导致瓶颈。

为了提高你的拉取请求被审查的机会，你应该

  • 引用一个开放的问题来解释非简单更改的 PR 目的

  • 确保你有适当的测试。这应该是任何 PR 的首要部分

  • 保持你的拉取请求尽可能简单。较大的 PR 审查时间更长

  • 确保 CI 处于绿色状态。否则审查者可能甚至不会查看

  • 保持更新你的拉取请求，无论是根据要求还是每隔几天