为 pandas 做贡献#

所有贡献、错误报告、错误修复、文档改进、增强功能和想法都是受欢迎的。

错误报告和增强请求#

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

该问题将展示给 pandas 社区，并开放给其他人评论/提供想法。

寻找一个可以贡献的问题#

如果你是第一次接触 pandas 或开源开发，我们建议在 GitHub 的“issues”标签页 中搜索你感兴趣的问题。未分配的带有 Docs 和 good first issue 标签的问题通常适合新贡献者。

一旦你发现了一个有趣的问题，最好将该问题分配给自己，这样其他人就不会重复这项工作。在 Github 问题上，用确切的文本 take 发表评论，以自动将问题分配给你（这可能需要几秒钟并可能需要刷新页面才能看到）。

如果由于任何原因你无法继续处理这个问题，请取消分配，以便其他人知道它再次可用。你可以检查已分配问题的列表，因为人们可能不再处理它们。如果你想处理一个已分配的问题，可以礼貌地询问当前的分配者是否可以接手（请至少在考虑问题工作中断之前允许一周的不活动时间）。

我们有几个 贡献者社区 沟通渠道，欢迎您加入并提问。其中包括新贡献者的定期会议、开发会议、开发邮件列表和贡献者社区的 Slack。所有 pandas 贡献者都欢迎加入这些空间，他们可以相互联系。即使是与我们合作了很长时间的维护者，在刚开始时也和您一样，他们很高兴欢迎您并支持您，帮助您了解我们的工作方式和资源位置。请查看下一部分以了解更多信息。

提交一个拉取请求#

版本控制, Git, 和 GitHub#

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

如果你是 Git 新手，可以参考这些资源来学习 Git。如果有需要，欢迎向 贡献者社区 寻求帮助：

此外，该项目遵循一种分叉工作流程，在此页面上有进一步描述，即贡献者分叉仓库、进行更改然后创建拉取请求。因此，请务必阅读并遵循本指南中的所有说明。

如果你是第一次通过在GitHub上分叉来为项目做贡献，可以查看 GitHub关于为项目做贡献的文档 。GitHub提供了一个使用测试仓库的快速教程，可能会帮助你更熟悉分叉仓库、克隆分叉、创建功能分支、推送更改和发起拉取请求。

以下是一些有用的资源，用于学习更多关于在GitHub上的分叉和拉取请求：

开始使用 Git#

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

创建一个 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，对于某个大于或等于 1 的 N）可能会破坏某些测试和功能，例如 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 分支。保持此分支中的任何更改仅针对一个错误或功能，以便清楚地了解该分支为 pandas 带来了什么。你可以有许多功能分支，并使用 git checkout 命令在它们之间切换。

当你想在创建分支后用主分支的更改更新功能分支时，请查看关于 更新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 特性分支的提交

git push origin shiny-new-feature

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

git remote -v

如果你按照上述描述添加了上游仓库，你将会看到类似的内容

origin  git@github.com:yourname/pandas.git (fetch)
origin  git@github.com: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: 修复了漏洞

    • 文档：文档的添加/更新

    • TST: 测试的添加/更新

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

    • PERF: 性能改进

    • TYP: 类型注解

    • CLN: 代码清理

  5. 在 Preview Discussion 标签中写入您更改的描述

  6. 点击 发送拉取请求。

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

更新你的拉取请求#

根据你在拉取请求中收到的评审，你可能需要对代码进行一些修改。你可以再次遵循 代码提交步骤 来处理任何反馈并更新你的拉取请求。

同样重要的是，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 都会自动用你的分支的更改更新你的拉取请求，并重新启动 持续集成 检查。

更新开发环境#

定期更新你的本地 main 分支与 pandas 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

成功拉取请求的提示#

如果你已经到了 Making a pull request 阶段，核心贡献者之一可能会查看。但请注意，只有少数人负责审查所有的贡献，这常常会导致瓶颈。

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

  • 引用一个未解决的问题 对于非平凡的更改，以澄清 PR 的目的

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

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

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

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