Contributing to pandas

Version control, Git, and GitHub

对于新用户，使用Git是促成pandas的更强大的方面之一。它可以很快拥有压倒性优势，但坚持下面的指导方针将有助于保持过程简单，大多是无故障。一如既往，如果你有困难，请随时要求帮助。

代码托管在GitHub上。要提供资料，您需要注册一个免费的GitHub帐户。我们使用Git进行版本控制，允许许多人在项目上一起工作。

一些伟大的资源学习Git：

• GitHub帮助页。
• NumPy的文档。
• Matthew Brett的Pydagogue。

Getting started with Git

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

Forking

你将需要你自己的fork来处理代码。转到pandas项目页，然后点击Fork按钮。你会想要克隆你的叉子到你的机器：

git clone git@github.com:your-user-name/pandas.git pandas-yourname
cd pandas-yourname
git remote add upstream git://github.com/pandas-dev/pandas.git

这将创建目录pandas-yourname，并将您的存储库连接到上游（主项目）pandas存储库。

在提交拉取请求后，测试套件将在Travis-CI上自动运行。但是，如果您希望在提交pull请求之前在分支上运行测试套件，则需要将Travis-CI连接到您的GitHub存储库。这样做的说明是这里。

Creating a branch

您希望您的主分支仅反映生产就绪代码，因此创建功能分支以进行更改。例如：

git branch shiny-new-feature
git checkout shiny-new-feature

以上可以简化为：

git checkout -b shiny-new-feature

这将您的工作目录更改为闪亮的新功能分支。Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to pandas. 你可以有许多闪亮的新功能，并使用git checkout命令在它们之间切换。

要更新此分支，您需要从主分支检索更改：

git fetch upstream
git rebase upstream/master

这将重播你的提交在最新的熊猫git master。如果这导致合并冲突，您必须在提交您的拉取请求之前解决这些冲突。如果您有未提交的更改，则需要在更新之前stash。这将有效地存储您的更改，他们可以在更新后重新应用。

Creating a development environment

创建pandas开发环境的简单方法如下。

• 安装Anaconda或miniconda
• 请确保您已cloned the repository
• cd到pandas源目录

通过运行以下命令，让conda创建一个名为pandas_dev的新环境或任何其他名称：

conda create -n pandas_dev --file ci/requirements_dev.txt

对于python 3环境：

conda create -n pandas_dev python=3 --file ci/requirements_dev.txt

这将创建新的环境，而不是触摸任何现有的环境，也没有任何现有的python安装。它将安装pandas的所有基本依赖项，以及开发和测试工具。如果要安装其他依赖项，可以按如下所示安装它们：

conda install -n pandas_dev -c pandas pytables scipy

要安装所有 pandas依赖项，您可以执行以下操作：

conda install -n pandas_dev -c pandas --file ci/requirements_all.txt

要在此环境中工作，Windows用户应activate，如下所示：

activate pandas_dev

Mac OSX / Linux用户应该使用：

source activate pandas_dev

然后，您将看到一条确认消息，表明您处于新的开发环境中。

要查看您的环境：

conda info -e

要在Windows中返回到主页根环境：

deactivate

在OSX / Linux中返回到您的主根环境：

source deactivate

请参阅完整的条件文档此处。

此时，您可以轻松地执行就地安装，如下一节所述。

Creating a Windows development environment

如果基于Windows系统，您需要安装编译器来构建安装环境。您将需要安装相应的Visual Studio编译器，VS 2008 for Python 2.7，VS 2010 for 3.4和VS 2015 for Python 3.5。

对于Python 2.7，您可以安装mingw编译器，它将等效于VS 2008：

conda install -n pandas_dev libpython

或使用Microsoft Visual Studio VC ++编译器Python。请注意，您必须检查x64框以安装x64扩展构建功能，因为默认情况下未安装。

对于Python 3.4，您可以下载并安装Windows 7.1 SDK。阅读下面的参考文件，因为在安装过程中可能会有各种各样的困难。

对于Python 3.5，您可以下载并安装Visual Studio 2015社区版。

这里有一些参考和博客：

• https://blogs.msdn.microsoft.com/pythonengineering/2016/04/11/unable-to-find-vcvarsall-bat/
• https://github.com/conda/conda-recipes/wiki/Building-from-Source-on-Windows-32-bit-and-64-bit
• https://cowboyprogrammer.org/building-python-wheels-for-windows/
• https://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/
• https://support.enthought.com/hc/en-us/articles/204469260-Building-Python-extensions-with-Canopy

Making changes

在更改代码之前，通常需要构建刚刚签出的代码。有两种主要的方法。

1. 开发pandas的最佳方式是通过运行以下命令来构建C扩展：

   python setup.py build_ext --inplace
   

   如果您在pandas源目录中启动Python解释器，您将调用构建的C扩展

2. 另一个非常常见的选择是执行pandas的develop安装：

   python setup.py develop
   

   这使得一个符号链接告诉Python解释器从你的开发目录中导入pandas。因此，您可以始终在您的系统上使用开发版本，而不必在克隆目录中。

About the pandas documentation

该文档用reStructuredText编写，这几乎就像用纯英语书写，并使用Sphinx构建。Sphinx文档对reST有一个很好的介绍。查看Sphinx文档以对文档执行更复杂的更改。

关于文档的一些其他重要的事情：

• pandas文档由两部分组成：代码本身中的docstrings和此文件夹中的文档pandas/doc/。

  docstrings提供了对各个功能的使用的清楚解释，而此文件夹中的文档包括每个主题的教程式概述以及一些其他信息（新增内容，安装等）。

• docstrings遵循Numpy Docstring Standard，在科学Python社区中广泛使用。这个标准规定了docstring的不同部分的格式。有关详细说明，请参阅本文档，或者查看一些现有函数以类似方式扩展它。

• 本教程大量使用ipython指令 sphinx扩展。此指令允许您将代码放在将在doc构建期间运行的文档中。例如：

  .. ipython:: python
  
      x = 2
      x**3
  

  将呈现为：

  In [1]: x = 2
  
  In [2]: x**3
  Out[2]: 8
  

  在doc构建过程中，几乎所有的代码示例都会运行（并保存输出）。这种方法意味着代码示例将始终是最新的，但它确实使doc构建更复杂。

pandoc doc/source/contributing.rst -t markdown_github > CONTRIBUTING.md

实用程序脚本scripts/api_rst_coverage.py可用于比较doc/source/api.rst中记录的方法列表（用于生成API参考页面）和实际的公共方法。这将识别doc/source/api.rst中记录的方法，这些方法实际上不是类方法，以及在doc/source/api.rst中没有记录的现有方法。 。

How to build the pandas documentation

conda install -n pandas_dev sphinx ipython nbconvert nbformat

python make.py html

python make.py clean
python make.py build

#omit autosummary and API section
python make.py clean
python make.py --no-api

# compile the docs with only a single
# section, that which is in indexing.rst
python make.py clean
python make.py --single indexing

pandas/docs/build/html/index.html

Code standards

pandas使用PEP8标准。有几个工具，以确保您遵守此标准。这是一些的更常见的PEP8问题：

• 我们将行长度限制为80个字符以提高可读性
• 传递参数应该在逗号后面有空格，例如。 foo（arg1， arg2， kw1 ='bar'）

Travis-CI将运行flake8工具，并报告代码中的任何文体错误。生成任何警告将导致构建失败；因此这些是向pandas提交代码的要求的一部分。

在提交代码以在diff上运行它是有帮助的：

git diff master | flake8 --diff

此外，我们编写了一个工具来检查您的提交是否为PEP8，pip install pep8radius。看看PEP8修复在你的分支vs主人：

pep8radius master --diff

并进行以下更改：

pep8radius master --diff --in-place

其他标准在代码样式wiki页面中列出。

请尝试保持向后兼容性。pandas有很多用户有很多现有的代码，所以不要打破它，如果可能的话。如果你认为需要破解，清楚地说明为什么作为pull请求的一部分。此外，在更改方法签名并在需要时添加弃用警告时要小心。

Test-driven development/code writing

pandas是认真的测试，并强烈鼓励贡献者拥抱测试驱动开发（TDD）。这个开发过程“依赖于重复一个非常短的开发周期：首先，开发人员编写一个（最初失败的）自动化测试用例，定义一个所需的改进或新的函数，然后产生最小量的代码通过该测试。 ，在实际写任何代码之前，你应该写你的测试。通常测试可以从原来的GitHub问题。但是，它总是值得考虑额外的用例和编写相应的测试。

添加测试是代码推送到pandas之后最常见的请求之一。因此，值得习惯于提前写测试，所以这从来不是一个问题。

像许多软件包一样，pandas使用鼻子测试系统和numpy.testing中的方便扩展。

def test_pivot(self):
    data = {
        'index' : ['A', 'B', 'C', 'C', 'B', 'A'],
        'columns' : ['One', 'One', 'One', 'Two', 'Two', 'Two'],
        'values' : [1., 2., 3., 3., 2., 1.]
    }

    frame = DataFrame(data)
    pivoted = frame.pivot(index='index', columns='columns', values='values')

    expected = DataFrame({
        'One' : {'A' : 1., 'B' : 2., 'C' : 3.},
        'Two' : {'A' : 1., 'B' : 2., 'C' : 3.}
    })

    assert_frame_equal(pivoted, expected)

nosetests pandas

  nosetests pandas/tests/[test-module].py
  nosetests pandas/tests/[test-module].py:[TestClass]
  nosetests pandas/tests/[test-module].py:[TestClass].[test_method]

.. versionadded:: 0.18.0

pd.test()

pip install git+https://github.com/spacetelescope/asv

asv continuous -f 1.1 upstream/master HEAD

asv continuous -f 1.1 -E virtualenv upstream/master HEAD

asv continuous -f 1.1 upstream/master HEAD -b ^groupby

asv continuous -f 1.1 upstream/master HEAD -b groupby.groupby_agg_builtins

asv run -e -E existing

asv run -e -E existing:python3.5

pip install git+https://github.com/pydata/vbench

./test_perf.sh -b master -t HEAD

Documenting your code

更改应反映在位于doc/source/whatsnew/vx.y.z.txt中的发行说明中。此文件包含每个发行版的正在进行的更改日志。向此文件添加条目以记录您的修复，增强或（不可避免的）中断更改。添加条目时，请务必包含GitHub问题编号（使用``GH1234``其中1234是问题/拉取请求编号）。

如果您的代码是增强功能，则很可能需要在现有文档中添加使用示例。这可以按照above部分进行。此外，为了让用户知道添加此功能的时间，使用versionadded指令。sphinx语法是：

.. versionadded:: 0.17.0

这将把文本新的版本0.17.0放置sphinx指令。当添加新的函数或方法（示例）或新的关键字参数（示例）时，也应将其放在docstring中。

Committing your code

保持样式修复一个单独的提交，使您的拉取请求更加可读。

完成更改后，您可以键入以下内容查看这些更改：

git status

如果你创建了一个新文件，它不是由git跟踪。通过键入以下内容添加：

git add path/to/file-to-be-added.py

做'git status'应该给出像：

# On branch shiny-new-feature
#
#       modified:   /relative/path/to/file-you-added.py
#

最后，使用解释性消息将更改提交到本地存储库。Pandas使用提交消息前缀和布局的约定。以下是一些常见的前缀以及何时使用它们的一般准则：

• ENH：增强，新功能
• BUG：错误修复
• DOC：文档的添加/更新
• TST：测试的添加/更新
• BLD：更新构建过程/脚本
• PERF：性能改进
• CLN：代码清理

以下定义如何构造提交消息。请使用GH1234或＃1234在提交消息中引用相关的GitHub问题。任何一种风格都很好，但前者通常是首选：

• 主题行具有80 chars。
• 一个空白行。
• （可选）提交消息体。

现在，您可以在本地存储库中提交更改：

git commit -m

Combining commits

如果你有多个提交，你可能想把它们合并成一个提交，通常被称为“压缩”或“rebasing”。这是包维护者在提交拉取请求时的常见请求，因为它维护了更紧凑的提交历史。要重命名您的提交：

git rebase -i HEAD~#

其中＃是要组合的提交数。然后你可以选择相关的提交消息并丢弃其他。

要压缩到主分支：

git rebase -i master

Use the s option on a commit to squash, meaning to keep the commit messages, or f to fixup, meaning to merge the commit messages.

然后，您将需要强行推动分支（见下文）以用新的替换当前提交：

git push origin shiny-new-feature -f

Pushing your changes

当您希望您的更改公开显示在您的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上提交拉取请求。

Review your code

当您准备要求进行代码审核时，请提交拉取请求。在你做之前，再次确保你已经遵循本文档中关于代码风格，测试，性能测试和文档的所有准则。您还应该仔细检查您的分支更改是根据它所基于的分支：

1. 在GitHub上导航到您的存储库 - https://github.com/your-user-name/pandas
2. 点击Branches
3. 单击功能部门的Compare按钮
4. 如果需要，请选择base和compare分支。这将分别是master和shiny-new-feature。

Finally, make the pull request

如果一切看起来不错，你准备提出一个拉请求。拉取请求是来自本地存储库的代码如何可用于GitHub社区，可以查看并最终合并到主版本。此拉取请求及其关联的更改将最终提交到主分支，并在下一个版本中可用。要提交拉款请求：

1. 在GitHub上导航到您的存储库
2. 点击拉动 请求按钮
3. 然后，您可以点击Commits和文件 已更改
4. 在预览 讨论标签中写入您对更改的说明
5. 点击发送 拉 请求。

然后，此请求将转到存储库维护人员，他们将查看代码。如果你需要做更多的更改，你可以在你的分支，将它们推送到GitHub，并拉动请求将自动更新。将它们推送到GitHub是通过：

git push -f origin shiny-new-feature

这将自动更新您的拉取请求与最新的代码，并重新启动Travis-CI测试。

如果您的拉取请求与pandas.io.gbq模块相关，请参阅Running Google BigQuery Integration Tests一节，为您的拉取请求配置Google BigQuery服务帐户在Travis-CI。

Delete your merged branch (optional)

一旦你的特性分支被接受到上游，你可能想要摆脱分支。首先，将上游主合并到你的分支，所以git知道它是安全的删除你的分支：

git fetch upstream
git checkout master
git merge upstream/master

然后你可以做：

git branch -d shiny-new-feature

确保使用小写的-d，否则git将不会警告你，如果你的功能分支没有被实际合并。

分支将仍然存在于GitHub上，所以删除它有：

git push origin --delete shiny-new-feature