为熊猫做贡献#

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

错误报告和增强请求#

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

然后，该问题将显示在 pandas 社区中，并接受其他人的评论/想法。

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

如果您是 pandas 或开源开发的新手，我们建议您搜索GitHub“问题”选项卡 以查找您感兴趣的问题。标记为“文档” 和“好第一期”的未分配问题 通常适合新贡献者。

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

如果出于某种原因您无法继续处理该问题，请取消分配它，以便其他人知道它再次可用。您可以检查已分配问题的列表，因为人们可能不再处理这些问题。如果您想处理已分配的工作，请随时询问当前的受让人是否可以接受（请允许至少一周的不活动时间，然后再考虑停止该问题的工作）。

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

提交拉取请求#

版本控制、Git 和 GitHub #

pandas 托管在GitHub上，要做出贡献，您需要注册一个免费的 GitHub 帐户。我们使用Git进行版本控制，以允许多人共同完成该项目。

如果您是 Git 新手，可以参考其中一些资源来学习 Git。如果需要，请随时联系贡献者社区寻求帮助：

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

如果您不熟悉通过 GitHub 上的 fork 为项目做出贡献，请查看有关为项目做出贡献的 GitHub 文档。 GitHub 提供了一个使用测试存储库的快速教程，可以帮助您更加熟悉分叉存储库、克隆分叉、创建功能分支、推送更改和发出拉取请求。

以下是一些有用的资源，可帮助您了解有关 GitHub 上的分叉和拉取请求的更多信息：

开始使用 Git #

GitHub 有有关安装 git、设置 SSH 密钥和配置 git 的说明。需要完成所有这些步骤，然后才能在本地存储库和 GitHub 之间无缝工作。

创建 pandas 的分支#

您将需要自己的 pandas（又名 fork）副本来处理代码。转到pandas 项目页面并点击Fork按钮。请在选择之前取消选中该框以仅复制主分支。你需要将你的 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

当您在创建分支后想要使用 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：错误修复

    • DOC：文档的添加/更新

    • TST：测试的添加/更新

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

    • PERF：性能改进

    • TYP：类型注释

    • CLN：代码清理

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

  6. 点击。Send Pull Request

然后，该请求发送给存储库维护人员，他们将审查代码。

更新您的拉取请求#

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

同样重要的是，pandasmain分支中的更新反映在您的拉取请求中。要使用 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

在本地更新功能分支后，您现在可以通过推送到 GitHub 上的分支来更新拉取请求：

git push origin shiny-new-feature

Any将自动使用分支的更改更新您的拉取请求，并重新启动持续集成检查。git push

更新开发环境#

main使用pandasmain 分支的更新定期更新本地分支并更新开发环境以反映开发过程中使用的各种包的任何更改非常重要。

如果使用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 处于绿色状态。审稿人甚至可能不会以其他方式看待

  • 根据请求或每隔几天不断更新您的拉取请求