为Pandas做贡献#
目录：
从哪里开始？#
欢迎所有的贡献、错误报告、错误修复、文档改进、增强和想法。
如果您是Pandas或开源开发的新手，我们建议您通过 GitHub "issues" tab 找出你感兴趣的问题。下面列出了一些问题 Docs 和 good first issue 在那里你可以开始。一旦您发现了一个有趣的问题，您就可以返回到这里来设置您的开发环境。
当你开始处理一个问题时，最好把这个问题分配给你自己，这样别人就不会重复你的工作了。GitHub仅限制将问题分配给项目的维护人员。在大多数项目中，直到最近，在Pandas项目中，投稿人都会添加评论，让其他人知道他们正在研究一个问题。虽然这是可以的，但您需要单独检查每个问题，并且不可能找到未分配的问题。
出于这个原因，我们实现了一种解决方法，包括添加包含确切文本的注释 take 。当你这样做时，GitHub的动作会自动向你分配问题(这需要几秒钟的时间，可能需要刷新页面才能看到它)。通过这样做，可以筛选问题列表并仅找到未分配的问题。
所以，找到一个开始对Pandas有贡献的问题的一个好方法是检查 unassigned good first issues 并给自己分配一个你喜欢的，写一条带有确切文本的评论 take 。
如果出于任何原因您无法继续处理该问题，请尝试取消分配它，以便其他人知道它再次可用。您可以查看已分配问题的列表，因为人们可能不再处理这些问题。如果您想从事已分配的工作，请随时询问当前受理人您是否可以接受(请允许至少一周的不活动时间，然后再考虑停止该问题的工作)。
您可以随时在 mailing list 或打开 Gitter 。
错误报告和增强请求#
臭虫报告是让大Pandas更稳定的重要组成部分。拥有一份完整的错误报告将允许其他人复制错误并提供修复的洞察力。看见 this stackoverflow article 和 this blogpost 获取有关编写好的错误报告的提示。
在上尝试生成错误的代码 main 分支通常是一项值得进行的练习，以确认漏洞仍然存在。搜索现有的错误报告和请求以查看问题是否已经报告和/或修复也是值得的。
错误报告必须：
包括一个简短的、自包含的重现该问题的Python代码片段。您可以使用以下命令很好地格式化代码 GitHub Flavored Markdown ：：
```python >>> from pandas import DataFrame >>> df = DataFrame(...) ... ```
包括Pandas及其附属物的完整版本字符串。您可以使用内置函数：：
>>> import pandas as pd >>> pd.show_versions()
解释为什么当前的行为是错误的/不受欢迎的，以及你期望的是什么。
然后，这个问题将出现在大Pandas社区，并接受其他人的评论/想法。
使用代码#
现在，您已经有了要修复的问题、要添加的增强功能或要改进的文档，您需要学习如何使用GitHub和Pandas代码库。
版本控制、Git和GitHub#
对于新用户来说，与Git合作是为Pandas做贡献的一个更令人望而生畏的方面。它可能很快就会变得不堪重负，但坚持下面的指导方针将有助于保持这个过程的直截了当和基本没有麻烦。一如既往，如果你有困难，请随时寻求帮助。
该代码驻留在 GitHub 。要投稿，您需要注册一个 free GitHub account 。我们用 Git 用于版本控制，以允许许多人在项目上共同工作。
学习Git的一些很好的资源：
这个 GitHub help pages 。
这个 NumPy documentation 。
马修·布雷特的 Pydagogue 。
Git入门#
GitHub has instructions 用于安装git、设置SSH密钥和配置git。在您可以在本地存储库和GitHub之间无缝工作之前，需要完成所有这些步骤。
分叉#
您将需要自己的分支来处理代码。转到 pandas project page 然后打到了 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
这将创建目录 pandas-yourname 并将您的存储库连接到上游(主项目) Pandas 存储库。
请注意，执行浅层克隆(使用 --depth==N ，对一些人来说 N 大于或等于1)可能会破坏某些测试和功能，如 pd.show_versions() 因为版本号不能再计算了。
创建分支#
您希望您的主分支只反映生产就绪的代码，因此创建一个特性分支来进行更改。例如：：
git branch shiny-new-feature
git checkout shiny-new-feature
上述事项可简化为：
git checkout -b shiny-new-feature
这会将您的工作目录更改为SHINY-NEW-FEATURE分支。将此分支中的任何更改保留为特定于一个错误或功能，以便清楚该分支给Pandas带来了什么。您可以拥有许多闪亮的新功能，并使用git签出命令在它们之间进行切换。
创建此分支时，请确保您的主分支使用最新的上游主版本。要更新本地主分支机构，您可以执行以下操作：
git checkout main
git pull upstream main --ff-only
如果要在创建分支后使用Main中的更改更新要素分支，请选中上的部分 updating a PR 。
把你的改变贡献给Pandas#
提交您的代码#
将样式修复保留为单独的提交，以使您的拉请求更具可读性。
进行更改后，您可以通过键入以下命令查看更改：
git status
如果你已经创建了一个新文件，那么它不会被git跟踪。通过键入以下命令进行添加：
git add path/to/file-to-be-added.py
再做一次‘git状态’应该会得到这样的结果：：
# On branch shiny-new-feature
#
# modified: /relative/path/to/file-you-added.py
#
最后，使用说明性消息将更改提交到本地存储库。Pandas使用提交消息前缀和布局的约定。以下是一些常见的前缀，以及何时使用它们的一般指南：
增强版：增强、新功能
错误：错误修复
DOC：对文档的添加/更新
TST：添加/更新测试
BLD：对构建过程/脚本的更新
Perf：性能改进
类型：类型批注
CLN：代码清理
下面定义了提交消息的结构。请使用GH1234或#1234在您的提交消息中引用相关的GitHub问题。任何一种风格都可以，但前者通常更受欢迎：
带有的主题行
< 80查斯。一行空行。
还可以选择提交消息正文。
现在，您可以在本地存储库中提交更改：：
git commit -m
推动您的更改#
当您希望您的更改公开出现在GitHub页面上时，请按下您的分支功能分支的提交：：
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上提交拉取请求。
检查您的代码#
当您准备好请求代码审查时，提交一个拉请求。在执行此操作之前，请再次确保您已遵循本文档中概述的有关代码样式、测试、性能测试和文档的所有指导原则。您还应该根据分支所基于的分支重新检查分支更改：
在giHub上导航到您的存储库--https://github.com/your-user-name/pandas
单击
Branches单击
Compare功能分支的按钮选择
base和compare分支机构，如有必要。这将是main和shiny-new-feature，分别为。
最后，发出拉入请求#
如果一切看起来都很好，您就可以发出拉入请求了。Pull请求是指GitHub社区可以使用本地存储库中的代码，并可以查看这些代码并最终将其合并到主版本中。此拉入请求及其相关更改最终将提交到主分支，并在下一个版本中可用。要提交拉式请求，请执行以下操作：
导航到GitHub上的存储库
单击
Pull Request按钮然后您可以点击
Commits和Files Changed最后一次确保一切正常将您的更改描述写在
Preview Discussion选项卡单击
Send Pull Request。
然后，此请求将发送给存储库维护人员，他们将审查代码。
更新您的拉取请求#
根据您在Pull请求上得到的审查，您可能需要对代码进行一些更改。在这种情况下，您可以在您的分支中创建它们，向该分支添加一个新的提交，将其推送到GitHub，拉取请求将自动更新。将它们再次推送到GitHub的方式是：：
git push origin shiny-new-feature
这将使用最新代码自动更新您的拉取请求，并重新启动 Continuous Integration 测试。
您可能需要更新Pull请求的另一个原因是为了解决与自您打开Pull请求以来已合并到主分支中的更改的冲突。
要做到这一点，您需要在分支中“合并上游主干”：
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 commit 来保存这些修复。
如果在您想要用Main更新分支时有未提交的更改，则需要 stash them prior to updating (see the stash docs )。这将有效地存储您的更改，并可在更新后重新应用这些更改。
在本地更新功能分支后，您现在可以通过推送到GitHub：：上的分支来更新您的拉取请求
git push origin shiny-new-feature
自动修复格式错误#
我们使用几种样式检查(例如 black ， flake8 ， isort )，它们在您发出拉取请求后运行。如果存在其中任何检查失败的情况，则可以评论：
@github-actions pre-commit
关于拉车的请求。这将触发自动修复格式错误的工作流。
要自动修复每次提交时的格式错误，您可以自己设置预提交。首先，创建一个Python environment 然后设置 pre-commit 。
删除合并的分支机构(可选)#
一旦你的功能分支被上游所接受，你可能会想要摆脱这个分支。首先，将上游Main合并到您的分支中，以便Git知道删除您的分支是安全的：：
git fetch upstream
git checkout main
git merge upstream/main
然后您可以执行以下操作：
git branch -d shiny-new-feature
请确保使用小写字母 -d ，否则，如果您的功能分支尚未实际合并，Git不会发出警告。
该分支仍将存在于GitHub上，因此要在那里删除它，请执行以下操作：
git push origin --delete shiny-new-feature
拉取请求成功的提示#
如果你已经成功晋级 Review your code 阶段，核心贡献者之一可能会看看。然而，请注意，少数人负责审查所有的贡献，这往往会导致瓶颈。
要提高您的拉式请求被审查的机会，您应该：
引用未解决的问题 为了明确公关的目的而做出的重大改变
确保你有适当的测试 。这些应该是任何公关的第一部分
让您的请求尽可能简单 。较大的公关需要更长的时间进行审核
确保配置项处于绿色状态 。评论者甚至可能看不出其他的样子
Keep Updating your pull request ，通过请求或每隔几天