对GeoPandas的贡献#

(投稿指南主要抄袭自 pandas )

概述#

我们非常欢迎对大熊猫的贡献。如果他们遵循这些指导方针，他们可能会更快地被接受。

在GeoPandas开发的这个阶段，首要任务是定义一个简单、可用和稳定的API，并拥有干净、可维护、可读的代码。业绩很重要，但不能以牺牲这些目标为代价。

总体而言，GeoPandas在适用时遵循熊猫项目的惯例。

尤其是在提交拉取请求时：

  • 所有现有的测试都应该通过。请确保测试套件通过，无论是在本地还是在 GitHub Actions 。GHA上的状态将在拉式请求中可见。GHA在您自己的分支上也会自动启用。要触发检查，请对您自己的叉子进行公关。

  • 新功能应该包括测试。请为您的代码编写合理的测试，并确保它们传递您的Pull请求。

  • 类、方法、函数等应该有文档字符串。文档字符串的第一行应该是独立的摘要。参数和返回值应显式记录。

  • 如果可能的话，遵循PEP 8。我们用 Black 和 Flake8 确保整个项目代码格式一致。有关更多详细信息，请参见 below 。

  • 导入应该首先与标准库导入分组，然后是第三方库导入，最后是GeoPandas导入。在每一组内，进口应按字母顺序排列。在可能的情况下始终使用绝对导入，在测试中需要时对本地导入使用显式相对导入。

  • GeoPandas仅支持Python3.8+。支持Python2的GeoPandas的最新版本是0.6。

贡献的七个步骤#

有七个基本步骤可以帮助你 GeoPandas ：

  1. 叉子 GeoPandas Git存储库

  2. 营造发展环境

  3. 安装 GeoPandas 相依性

  4. vt.制造一个 development 建造 GeoPandas

  5. 更改代码并添加测试

  6. 更新文档

  7. 提交拉取请求

下面详细介绍了这7个步骤中的每个步骤。

1)分叉 GeoPandas 使用Git的存储库#

对于新用户来说，使用Git是为 GeoPandas *。它可能很快就会变得不堪重负，但坚持下面的指导方针将有助于保持这个过程的直截了当和基本没有麻烦。一如既往，如果你有困难，请随时寻求帮助。

该代码驻留在 GitHub 。要投稿，您需要注册一个 free GitHub account 。我们用 Git 用于版本控制，以允许许多人在项目上共同工作。

学习Git的一些很好的资源：

Git入门#

GitHub has instructions 用于安装git、设置SSH密钥和配置git。在您可以在本地存储库和GitHub之间无缝工作之前，需要完成所有这些步骤。

分叉#

您将需要自己的分支来处理代码。转到 GeoPandas project page 然后打到了 Fork 纽扣。您将想要将您的分支克隆到您的计算机：：

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

这将创建目录 geopandas-yourname 并将您的存储库连接到上游(主项目) GeoPandas 存储库。

一旦您的Pull请求被提交，测试套件将在GitHub操作上自动运行。测试套件还将在您的分支上自动运行，因此您可以在提交Pull请求之前对其进行检查。

创建分支#

您希望您的主分支只反映生产就绪的代码，因此创建一个特性分支来进行更改。例如：：

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

上述事项可简化为：

git checkout -b shiny-new-feature

这会将您的工作目录更改为SHINY-NEW-FEATURE分支。将此分支中的任何更改保留为特定于一个错误或功能，以便清楚该分支带来了什么 GeoPandas 。您可以拥有许多闪亮的新功能，并使用git签出命令在它们之间进行切换。

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

git fetch upstream
git rebase upstream/main

这将在最新的GeoPandas git Main上重播您的承诺。如果这会导致合并冲突，您必须在提交Pull请求之前解决这些冲突。如果您有未提交的更改，则需要 stash 在更新之前对它们进行更新。这将有效地存储您的更改，并可在更新后重新应用这些更改。

2)营造发展环境#

开发环境是一个虚拟空间，您可以在其中独立安装 GeoPandas 。这使得您可以轻松地在一个地方保存稳定版本的Python，并在另一个地方保存开发版本(您在玩代码时可能会破坏它)。

一个简单的方法来创建 GeoPandas 开发环境如下：

使用提供的环境#

GeoPandas 提供一个环境，其中包含开发所需的依赖项。环境文件位于repo的顶层，名为 environment-dev.yml 。您可以通过导航到 GeoPandas 源目录并正在运行：：

conda env create -f environment-dev.yml

这将创建一个名为 geopandas_dev 。

手动创建环境#

或者，也可以手动创建开发环境。为此，告诉Conda创建一个名为 geopandas_dev ，或您希望为此环境使用的任何其他名称，方法是运行：：

conda create -n geopandas_dev python

这将创建新的环境，并且不会影响任何现有环境，也不会影响任何现有的Python安装。

与环境合作#

要在这种环境中工作，您需要 activate 它。以下说明应适用于Windows、Mac和Linux：

conda activate geopandas_dev

一旦您的环境被激活，您将看到一条确认消息，指示您处于新的开发环境中。

要查看您的环境：

conda info -e

要返回到您的主根环境：：

conda deactivate

查看完整的Conda文档 here 。

此时，您可以轻松地执行 发展 安装，如以下各节中所述。

3)安装依赖项#

奔跑 GeoPandas 在开发环境中，您必须首先安装 GeoPandas 的依赖项。如果您使用的是第2节中提供的环境，请跳过此步骤并继续第4节。如果您手动创建环境，我们建议使用以下命令安装依赖项(在您的开发环境激活后执行)：

conda install -c conda-forge pandas fiona shapely pyproj rtree pytest

这应该会安装所有必要的依赖项。

4)进行开发构建#

一旦依赖项就位，通过导航到 GeoPandas 存储库和运行：：

python setup.py develop

5)做修改和写测试#

GeoPandas 认真对待测试，并强烈鼓励贡献者接受 test-driven development (TDD) 。这个开发过程“依赖于非常短的开发周期的重复：首先，开发人员编写(最初失败的)自动化测试用例，定义所需的改进或新功能，然后生成通过该测试所需的最少代码。”因此，在实际编写任何代码之前，您应该编写测试。通常，测试可以从最初的GitHub问题开始。然而，考虑其他用例并编写相应的测试总是值得的。

添加测试是将代码推送到 GeoPandas 。因此，养成提前编写测试的习惯是值得的，这样就永远不会有问题。

GeoPandas 使用 pytest testing system 和方便的扩展 numpy.testing 。

写试卷#

所有的测试都应该进入 tests 目录。该文件夹包含许多当前的测试示例，我们建议您从这些示例中寻找灵感。

这个 .util 模块有一些特殊的 assert 这些函数使您可以更轻松地说明GeoSeries或GeoDataFrame对象是否等价。验证代码是否正确的最简单方法是显式构造预期的结果，然后将实际结果与预期的正确结果进行比较，例如使用函数 assert_geoseries_equal 。

运行测试套件#

然后可以在您的Git克隆中直接运行测试(无需安装 GeoPandas )键入：：

pytest

6)更新文档#

GeoPandas 文档位于 doc 文件夹。对文档的更改是通过修改 source 内的文件夹 doc 。 GeoPandas Docs混合使用reStrutiredText语法用于 rst 文件， which is explained here 和myst语法，用于 md 文件 explained here 。文档字符串跟在 Numpy Docstring standard 。一些页面和示例是使用Jupyter笔记本转换为文档 nbsphinx 。Jupyter笔记本应该存储在没有输出的地方。

我们强烈建议您遵循 Google developer documentation style guide 更新或创建新文档时。

进行更改后，您可以尝试使用Shinx构建文档，以确定它们是否正确呈现。为此，您可以导航到 doc 文件夹：：

cd doc

并键入：：

make html

生成的html页面将位于 doc/build/html 。

如果出现任何错误，您可以尝试使用 make html 在新的环境中基于 doc 文件夹。您可能需要将Jupyter内核注册为 geopandas_docs 。使用CONDA：：

cd doc
conda env create -f environment.yml
conda activate geopandas_docs
python -m ipykernel install --user --name geopandas_docs
make html

对于较小的更新，您可以跳过 make html Part as reStruredText和myst语法通常非常简单。

7)提交拉取请求#

一旦进行了更改并将它们推送到派生的存储库，您就可以提交一个拉取请求，将它们集成到 GeoPandas 代码库。

您可以在中找到拉取请求(或PR)教程 GitHub's Help Docs 。

造型指南&Linting#

GeoPandas遵循 PEP8 标准和用途 Black 和 Flake8 确保整个项目代码格式一致。

持续集成(GitHub操作)将运行这些工具并报告代码中的任何样式错误。因此，在提交代码以自己运行检查之前：

black geopandas
git diff upstream/main -u -- "*.py" | flake8 --diff

要自动格式化代码，请执行以下操作。此外，许多编辑器都有可以应用的插件 black 当您编辑文件时。

或者(但推荐)，您可以设置 pre-commit hooks 要自动运行 black 和 flake8 当你做出一个愚蠢的承诺时。中提供的开发环境 environment-dev.yml ，您必须先安装 pre-commit ：：

$ python -m pip install pre-commit

然后从geopandas存储库的根目录安装 pre-commit 包括在 GeoPandas ：：

$ pre-commit install

然后 black 和 flake8 将在您每次提交更改时自动运行。可以使用以下命令跳过这些检查 git commit --no-verify 。

提交消息约定#

使用说明性消息将更改提交到本地存储库。GeoPandas使用熊猫约定来提交消息前缀和布局。以下是一些常见的前缀，以及何时使用它们的一般指南：

  • 增强版：增强、新功能

  • 错误：错误修复

  • DOC：对文档的添加/更新

  • TST：添加/更新测试

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

  • Perf：性能改进

  • 类型：类型批注

  • CLN：代码清理

下面定义了提交消息的结构。请使用GH1234或#1234在您的提交消息中参考相关的GitHub问题。任何一种风格都可以，但前者通常更受欢迎：

  • 带有的主题行 < 80 查斯。

  • 一行空行。

  • 还可以选择提交消息正文。

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

git commit -m

上一页

社区

下一页

GeoPandas项目行为守则