参与贡献 pandas#

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

错误报告和增强请求 #

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

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

找到要贡献的问题 #

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

一旦你找到了一个感兴趣的问题，最好将问题分配给自己，这样就没有其他人重复工作。在 Github 问题上，评论精确文本 take 将自动将问题分配给你（这需要几秒钟，并且可能需要刷新页面才能看到）。

如果出于某种原因你无法继续处理该问题，请取消分配，以便其他人知道它再次可用。你可以检查已分配问题的列表，因为人们可能不再处理它们。如果你想处理一个已分配的问题，请随时礼貌地询问当前分配者你是否可以接手（请至少等待一周的不活动期，然后再考虑该问题已中断）。

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

提交拉取请求 #

版本控制、Git 和 GitHub #

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

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

Git 文档.
Numpy 的 Git 资源教程。

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

如果你是 GitHub 上通过派生参与项目的新手，请查看GitHub 关于参与项目的文档。GitHub 提供了一个使用测试仓库的快速教程，这可能有助于你更熟悉派生仓库、克隆派生、创建功能分支、推送更改和发出拉取请求。

以下是一些关于在 GitHub 上了解更多派生和拉取请求的有用资源

Git 入门 #

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

创建 pandas 的派生（fork）#

你需要一份自己的 pandas 副本（即派生，fork）来处理代码。访问 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 命令在它们之间切换。

如果你想在创建分支后，用 main 分支的更改来更新功能分支，请查看更新拉取请求一节。

进行代码更改 #

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

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

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 社区进行审查并合并到项目中，以出现在下一个发布版本中的方式。要提交拉取请求

导航到你的 GitHub 仓库
点击 Compare & pull request 按钮
然后你可以点击 Commits 和 Files Changed 再次确认一切正常
编写一个带有前缀的描述性标题。pandas 对标题前缀有约定。以下是一些常见的前缀以及何时使用它们的一般指南
- ENH: 增强，新功能
- BUG: 错误修复
- DOC: 文档添加/更新
- TST: 测试添加/更新
- BLD: 构建过程/脚本更新
- PERF: 性能改进
- TYP: 类型注解
- CLN: 代码清理
在 Preview Discussion 选项卡中编写你的更改描述
点击 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/ 以了解如何操作的解释。

一旦冲突解决，运行

git add -u 来暂存任何你已更新的文件；
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

成功拉取请求的技巧 #

如果你已经到了提出拉取请求阶段，其中一位核心贡献者可能会进行查看。但是请注意，少数人负责审查所有贡献，这通常会导致瓶颈。

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

对于非琐碎的更改，引用一个开放问题以阐明拉取请求的目的
确保你有适当的测试。这些应该是任何拉取请求的第一部分
让你的拉取请求尽可能简单。较大的拉取请求需要更长的审查时间
确保 CI 处于绿色状态。否则，审查者甚至可能不会查看
持续更新你的拉取请求，无论是根据要求还是每隔几天