为 pandas 贡献代码#

我们欢迎所有的贡献，包括 Bug 报告、Bug 修复、文档改进、功能增强和创意。

Bug 报告和功能增强请求#

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

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

寻找可以贡献的 issue#

如果你是 pandas 或开源开发的新手，我们建议搜索 GitHub 的 “issues” 标签页 来查找你感兴趣的 issue。未分配的、带有 Docs 标签和 good first issue 标签的 issue 通常适合新贡献者。

找到一个你感兴趣的 issue 后，请留下评论说明你打算开始处理它。如果其他人已经对该 issue 发表了评论，但他们在过去 2-3 周内在该 issue 或 pull request 上缺乏活动，你可以接手。

如果你因任何原因无法继续处理该 issue，请在该 issue 上留下评论，以便其他人知道它再次可用。你可以查看已分配 issue 的列表，因为有些人可能不再处理它们了。

我们有几个 贡献者社区 通信渠道，欢迎你加入并提出问题。其中包括面向新贡献者的定期会议、开发会议、开发邮件列表以及面向贡献者社区的 Slack。所有 pandas 贡献者都欢迎参加这些可以互相交流的空间。即使是长期以来与我们合作的维护者，在开始时也和你一样，他们很乐意欢迎你并在你了解我们的工作方式和一切事物时为你提供支持。请看下面的部分了解更多信息。

提交 Pull Request#

版本控制、Git 和 GitHub#

pandas 托管在 GitHub 上，要贡献代码，你需要注册一个免费的 GitHub 账户。我们使用 Git 进行版本控制，以便多人协作开发项目。

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

此外，该项目遵循一个在此页面上进一步描述的 Forking 工作流程，贡献者 Fork 仓库，进行更改，然后创建一个 Pull Request。因此，请务必阅读并遵循本指南中的所有说明。

如果你是第一次通过 GitHub Fork 项目，请查阅GitHub 关于贡献项目的文档。GitHub 提供了一个使用测试仓库的快速教程，这可能有助于你更熟悉 Fork 仓库、Clone Fork、创建 Feature 分支、推送更改和发起 Pull Request。

以下是一些关于在 GitHub 上了解 Fork 和 Pull Request 的有用资源：

Git 入门#

GitHub 提供了关于安装 Git、设置 SSH 密钥和配置 Git 的说明。在可以在本地仓库和 GitHub 之间无缝工作之前，需要完成所有这些步骤。

Fork pandas#

你需要拥有自己的 pandas 副本（即 Fork）来处理代码。前往 pandas 项目页面，然后点击 Fork 按钮。请取消选中“仅复制主分支”的复选框，然后选择 Create Fork。然后你需要将你的 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()，因为无法再计算版本号。

创建 Feature 分支#

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

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

然后，创建一个 Feature 分支来做你的更改。例如：

git checkout -b shiny-new-feature

这会将你的工作分支从 main 切换到 shiny-new-feature 分支。将此分支中的任何更改限制在一个 Bug 或功能上，这样就可以清楚该分支为 pandas 带来了什么。你可以拥有多个 Feature 分支，并使用 git checkout 命令在它们之间切换。

当你想要在创建分支后用 main 中的更改更新 Feature 分支时，请参阅关于更新 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 页面上时，请推送你的 Forked Feature 分支的提交：

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 上提交一个 Pull Request。

发起 Pull Request#

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

如果一切看起来都很好，你就可以发起 Pull Request 了。Pull Request 是你的本地仓库中的代码如何让 GitHub 社区进行审查并合并到项目中，以出现在下一个版本中。要提交 Pull Request：

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

  2. 点击 Compare & pull request 按钮

  3. 你还可以点击 Commits 和 Files Changed 来最后一次检查一切是否正常。

  4. 写一个包含前缀的描述性标题。pandas 使用标题前缀约定。以下是一些常见的以及何时使用的通用指南：

    • ENH: Enhancement，新功能

    • BUG: Bug 修复

    • DOC: 文档的添加/更新

    • TST: 测试的添加/更新

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

    • PERF: 性能改进

    • TYP: 类型注解

    • CLN: 代码清理

  5. 在 Preview Discussion 选项卡中写下你的更改描述。

  6. 点击 Send Pull Request。

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

更新你的 Pull Request#

根据你对 Pull Request 的审查，你可能需要对代码进行一些更改。你可以按照 代码提交步骤 再次进行，以处理任何反馈并更新你的 Pull Request。

同时，保持 pandas main 分支的更新反映在你的 Pull Request 中也很重要。要用 pandas main 分支中的更改来更新你的 Feature 分支，请运行：

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 文档）。这将有效地存储你的更改，并在更新后重新应用它们。

在本地更新了 Feature 分支后，你现在可以通过推送到 GitHub 上的分支来更新你的 Pull Request：

git push origin shiny-new-feature

任何 git push 都将自动更新你的 Pull Request 中的分支更改，并重新启动 持续集成 检查。

更新开发环境#

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

如果使用 conda，请运行：

git checkout main
git fetch upstream
git merge upstream/main
conda activate pandas-dev
conda 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

成功的 Pull Request 技巧#

如果你已经进行到 发起 Pull Request 阶段，核心贡献者之一可能会审阅。但请注意，只有少数人负责审查所有贡献，这通常会导致瓶颈。

为了提高你的 Pull Request 被审查的机会，你应该：

  • 引用一个开放的 issue 来处理非微小的更改，以澄清 PR 的目的

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

  • 尽量保持你的 Pull Request 简单。较大的 PR 需要更长的审查时间

  • 确保 CI 处于绿色状态。否则，审阅者可能根本不会查看

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