为GeoPandas贡献代码#

(贡献指南主要复制自 pandas)

概述#

对GeoPandas的贡献非常欢迎。如果遵循这些指南，它们可能会更快被接受。

在GeoPandas开发的这个阶段，优先事项是定义一个简单、可用且稳定的API，并拥有干净、可维护、可读的代码。性能很重要，但不能以牺牲这些目标为代价。

通常，GeoPandas遵循pandas项目的惯例，适用时。

特别是在提交拉取请求时：

  • 所有现有的测试都应该通过。请确保测试套件在本地和 GitHub Actions上都能通过。GHA的状态将在拉取请求中可见。GHA在你的分叉上也是自动启用的。要触发检查，请向你自己的分叉提交一个PR。

  • 新功能应包括测试。请为您的代码编写合理的测试，并确保它们在您的拉取请求中通过。

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

  • 尽可能遵循PEP 8。我们使用 ruff 来确保项目中代码格式的一致性。有关更多细节，请参见 下面。

  • 导入应该首先与标准库导入分组，其次是第三方库导入，最后是GeoPandas导入。在每个分组内，导入应该按字母顺序排列。尽可能使用绝对导入，对于必要的局部导入，在测试中使用显式相对导入。

  • GeoPandas 仅支持 Python 3.10 及以上版本。

  • 除非您的拉取请求仅实现小的更改或仅涉及内部工作，否则请确保它包含一条说明在CHANGELOG.md文件中更改的内容的备注。

贡献的七个步骤#

为GeoPandas贡献有七个基本步骤：

  1. 分叉GeoPandas git代码库

  2. 创建开发环境

  3. 安装 GeoPandas 依赖项

  4. 制作一个 development 版本的 GeoPandas

  5. 对代码进行更改并添加测试

  6. 更新文档

  7. 提交一个拉取请求

以下每个步骤都详细列出在下面。

1) 使用Git分叉GeoPandas仓库#

对于新用户来说，使用Git是为GeoPandas贡献代码时最令人生畏的方面之一。 这很快就会变得让人感到不知所措，但是遵循以下指南将帮助保持过程 简单明了，且大多数情况下不会出错。 与往常一样，如果您遇到困难，请 随时寻求帮助。

代码托管在 GitHub 上。要贡献代码，您需要注册一个 免费的 GitHub 账户。我们使用 Git 进行版本控制，以便让多人能够在该项目上协同工作。

学习Git的一些优秀资源：

开始使用Git#

GitHub 有安装 git、设置 SSH 密钥和配置 git 的说明。在您能在本地仓库和 GitHub 之间无缝工作之前，所有这些步骤都需要完成。

分支#

您需要自己的分支来处理代码。请访问GeoPandas项目页面并点击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 仓库。

一旦提交您的拉取请求，测试套件将在GitHub Actions上自动运行。测试套件也会在您的分支上自动运行，以便您在提交拉取请求之前进行检查。

创建一个分支#

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

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

上述内容可以简化为：

git checkout -b shiny-new-feature

这会将你的工作目录更改为shiny-new-feature分支。 将此分支中的任何更改保持特定于一个bug或特性，以便清楚地了解该分支为GeoPandas带来了什么。你可以有许多shiny-new-features，并使用git checkout命令在它们之间切换。

要更新此分支，您需要从主分支中获取更改：

git fetch upstream
git rebase upstream/main

这将把你的提交重放到最新的 GeoPandas git 主分支上。如果这导致合并冲突，你必须在提交你的拉取请求之前解决这些冲突。如果你有未提交的更改，你需要在更新之前stash它们。这将有效地保存你的更改，并且可以在更新后重新应用。

2) 创建开发环境#

开发环境是一个虚拟空间，您可以在其中保持GeoPandas的独立安装。这使得在一个地方方便地保持一个稳定版本的python用于工作，而在另一个地方保持一个开发版本（您可能在玩代码时会破坏它）。

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

使用提供的环境#

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

conda env create -f environment-dev.yml

这将创建一个名为 geopandas_dev 的新conda环境。

手动创建环境#

或者，可以手动创建一个开发环境。为此，通过运行以下命令，让conda创建一个名为 geopandas_dev 的新环境，或者您希望为此环境指定的其他任何名称：

conda create -n geopandas_dev python

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

与环境合作#

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

conda activate geopandas_dev

一旦您的环境被激活，您将看到一条确认消息，以表明您已进入新的开发环境。

查看您的环境：

conda info -e

要返回您的主环境：

conda deactivate

查看完整的conda文档 这里。

在这一点上，您可以轻松进行 开发 安装，如下一节所述。

3) 安装依赖#

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

conda install -c conda-forge pandas pyogrio shapely pyproj pytest

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

4) 创建开发版本#

一旦依赖项就位，通过导航到GeoPandas库的git克隆并运行以下命令进行原地构建：

python -m pip install -e .

5) 进行更改并编写测试#

GeoPandas 非常重视测试，并强烈鼓励贡献者采用 测试驱动开发 (TDD)。 这个开发过程“依赖于非常短的开发周期的重复： 首先，开发者编写一个（最初失败的）自动化测试用例，以定义期望的 改进或新功能，然后生成通过该测试所需的最少代码。” 因此，在实际编写任何代码之前，您应该先编写测试。通常，测试可以来自原始的 GitHub 问题。 然而，始终值得考虑额外的用例，并编写相应的测试。

在代码推送到GeoPandas之后，添加测试是最常见的请求之一。因此，养成提前编写测试的习惯是值得的，这样就永远不成问题。

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

编写测试#

所有测试应该放入 tests 目录中。该文件夹包含许多当前的测试示例，我们建议可以参考这些示例以获取灵感。

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

运行测试套件#

然后可以通过输入下列命令直接在您的 Git 克隆中运行测试（无需安装 GeoPandas）：

pytest

6) 更新文档#

GeoPandas 文档位于 doc 文件夹中。对文档的更改是通过修改 doc 中的 source 文件夹内的适当文件来完成的。GeoPandas 文档使用 reStructuredText 语法混合用于 rst 文件，在这里解释，以及用于 md 文件的 MyST 语法 在这里解释。文档字符串遵循 Numpy Docstring 标准。某些页面和示例是转换为文档的 Jupyter 笔记本，使用 nbsphinx。Jupyter 笔记本应未包含输出进行存储。

我们强烈建议您在更新或创建新文档时遵循Google开发者文档风格指南。

一旦您进行了更改，您可以通过使用sphinx构建文档来检查它们是否正确呈现。为此，您可以导航到doc文件夹：

cd doc

及类型：

make html

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

如果出现任何错误，您可以尝试在基于environment.yml规范的新环境中使用 make html。您可能需要将 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 这个部分，因为reStructuredText和MyST语法通常是非常简单的。

7) 提交拉取请求#

一旦你进行了更改并将它们推送到你的分支仓库，接下来你需要提交一个拉取请求，以将它们整合到GeoPandas代码库中。

您可以在GitHub的帮助文档中找到拉取请求（或PR）教程。

风格指南与代码检查#

GeoPandas遵循PEP8标准，并使用ruff确保整个项目的一致代码格式。

持续集成（GitHub Actions）将运行这些工具并报告您代码中的任何样式错误。因此，在提交代码之前，自己运行检查是很有帮助的：

ruff format geopandas
ruff check geopandas
git diff upstream/main -u -- "*.py" | ruff check .

自动格式化您的代码。此外，许多编辑器都有插件可以在您编辑文件时应用 ruff。

可选（但推荐），您可以设置pre-commit hooks以在您进行git提交时自动运行ruff。如果您没有使用environment-dev.yml中提供的开发环境，则必须先安装pre-commit：

$ python -m pip install pre-commit

在geopandas仓库的根目录下，您应该安装GeoPandas中包含的pre-commit：

$ pre-commit install

然后 ruff 会在你每次提交更改时自动运行。你可以通过 git commit --no-verify 跳过这些检查。

提交消息约定#

将您的更改提交到本地仓库，并附上说明性的信息。GeoPandas 使用pandas的提交信息前缀和布局约定。以下是一些常见的前缀以及使用它们的一般指南：

  • 增强：增强，新功能

  • 错误：错误修复

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

  • TST: 对测试的添加/更新

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

  • PERF：性能改善

  • TYP: 类型注释

  • CLN: 代码清理

以下定义了提交信息应如何结构化。请在您的提交信息中使用 GH1234 或 #1234 引用相关的 GitHub 问题。两种样式都可以，但前者通常更受欢迎：

  • 一个主题行，长度少于 < 80 个字符。

  • 一个空行。

  • 可选的提交信息主体。

现在你可以提交你在本地仓库中的更改：

git commit -m