为 pandas 贡献代码#

欢迎所有贡献、错误报告、错误修复、文档改进、增强和想法。

错误报告和增强请求#

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

然后，问题将显示给 pandas 社区，并开放供其他人评论/提出想法。

寻找要贡献的问题#

如果您是 pandas 或开源开发的新手，我们建议您搜索GitHub 的“问题”选项卡，以找到您感兴趣的问题。未分配的问题标记为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 副本（也称为分支）才能处理代码。访问 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 分支。将此分支中的任何更改限制为一个错误或功能，以便清楚地了解该分支为 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 页面上公开显示时，请推送您分叉的功能分支的提交

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: 错误修复

    • 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 操作都会自动使用您分支的更改更新您的拉取请求，并重新启动 持续集成 检查。

更新开发环境#

定期更新本地 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

成功提交请求的技巧#

如果您已进入 提交请求 阶段，核心贡献者之一可能会查看。但是请注意，少数人负责审查所有贡献，这通常会导致瓶颈。

为了提高您的提交请求被审查的机会，您应该

  • 引用一个开放问题，以便对非平凡的更改进行澄清，以阐明 PR 的目的

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

  • 保持您的提交请求尽可能简单。较大的 PR 需要更长的时间才能审查

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

  • 保持 更新您的提交请求，无论是根据要求还是每隔几天