概述

感谢您花时间做出贡献！我们感谢所有贡献，从报告错误到实现新功能。如果您阅读本指南后仍不清楚如何操作，请通过 Discord 联系我们。

报告错误

我们使用 GitHub issues 来跟踪错误和建议的改进。您可以通过打开一个 新 issue 来报告错误。请根据您使用的语言（Rust / Python）选择相应的 issue 类型。

在创建错误报告之前，请检查您的错误是否已被报告，以及该错误是否存在于 Polars 的最新版本中。如果您发现一个已关闭的 issue 似乎报告了您正在经历的相同错误，请打开一个新 issue 并在您的 issue 描述中包含原始 issue 的链接。

请在您的错误报告中包含尽可能多的详细信息。这些信息有助于维护者更快地解决问题。

建议改进

我们使用 GitHub issues 来跟踪错误和建议的改进。您可以通过打开一个 新功能请求 来建议改进。在创建改进建议之前，请检查是否已存在类似的 issue。

请描述您想要的行为和原因，并提供示例说明如果添加了您的功能，Polars 将如何使用。

贡献代码库

选择问题

通过浏览 issue 跟踪器，找到您想要处理的 issue。您可以随意选择任何带有“accepted”标签且尚未分配的 issue。我们使用“help wanted”标签来表示我们非常希望解决的 issue。

如果您是首次贡献者，您可能希望寻找标记为“good first issue”的 issue。Polars 代码库相当复杂，因此从一个小 issue 开始将有助于您熟悉环境！

如果您想承担某个 issue，请在该 issue 上评论告知其他人。您可以使用该 issue 讨论可能的解决方案。

设置本地环境

Polars 的开发流程依赖于 Rust 和 Python，这意味着设置您的本地开发环境并非易事。如果您遇到问题，请通过 Discord 联系我们。

注意

如果您是 Windows 用户，以下步骤可能无法按预期工作。请尝试使用 WSL 进行开发。在原生 Windows 环境下，您可能需要手动将 toolchain.toml 的内容复制到 py-polars/toolchain.toml，因为 Git for Windows 可能无法正确处理符号链接。

配置 Git

要为 Polars 做出贡献，您需要一个免费的 GitHub 帐户并在您的机器上安装 git。首先分叉 Polars 仓库，然后使用 git 克隆您分叉的仓库

git clone https://github.com/<username>/polars.git
cd polars

（可选）设置 upstream 远程仓库，以便将来您可以将您的分叉与 Polars 仓库同步

git remote add upstream https://github.com/pola-rs/polars.git
git fetch upstream

安装依赖

为了高效地在 Polars 上工作，您需要 Rust、Python 和 dprint。

首先，使用 rustup 安装 Rust。初始安装后，您还需要安装 nightly 工具链

rustup toolchain install nightly --component miri

接下来，安装 Python，例如使用 pyenv。我们建议使用最新的 Python 版本（3.13）。请确保您已停用任何活动的虚拟环境（命令：deactivate）或 conda 环境（命令：conda deactivate），因为以下步骤将为 Polars 创建一个新的虚拟环境。即使您只打算处理 Rust 代码，也需要 Python，因为我们依赖 Python 测试来验证所有功能。

最后，安装 dprint。这不是严格要求，但建议安装，因为我们使用它来自动格式化某些文件类型。

现在，您可以通过进入 py-polars 目录并运行测试套件来检查一切是否正常工作（警告：首次运行可能会很慢）

cd py-polars
make test

注意

您需要安装 CMake 才能使 make test 工作。

这将执行多项操作：

• 使用 Python 在 .venv 文件夹中创建一个虚拟环境。
• 使用 pip 和 uv 安装所有用于开发、代码检查和构建文档的 Python 依赖项。
• 使用 Rust 在您的虚拟环境中编译并安装 Polars。建议至少 8GB 内存以确保此步骤顺利运行。
• 使用 pytest 在您的虚拟环境中运行 Python 单元测试

注意

有少量专业依赖项默认不会安装。如果您正在运行特定测试并遇到关于缺少依赖项的错误消息，请尝试运行 make requirements-all 来安装 所有 已知的依赖项）。

通过运行以下命令检查代码检查是否也正常工作：

make pre-commit

请注意，我们实际上不使用 pre-commit 工具。我们使用 Makefile 来方便地运行以下格式化和代码检查工具：

• ruff
• mypy
• rustfmt
• clippy
• dprint

如果这一切都正常运行，您就可以开始为 Polars 代码库贡献了！

更新开发环境

依赖项会定期更新 - 至少每月一次。如果您不保持环境最新，您可能会发现测试或 CI 检查失败，或者根本无法构建 Polars。

要更新您的环境，首先请确保您的分叉与 Polars 仓库同步

git checkout main
git fetch upstream
git rebase upstream/main
git push origin main

通过运行以下命令将所有 Python 依赖项更新到最新版本：

make requirements

如果 Rust 工具链版本已更新，您应该更新您的 Rust 工具链。之后运行 cargo clean 以确保您的 Cargo 文件夹不会变得太大

rustup update
cargo clean

处理您的问题

从您本地仓库的 main 分支创建一个新的 git 分支，然后开始编码！

Rust 代码位于 crates 目录中，而 Python 代码库位于 py-polars 目录中。这两个目录都包含一个 Makefile，其中包含有用的命令。最值得注意的是：

• make test 用于运行测试套件（有关更多信息，请参阅测试套件文档）
• make pre-commit 用于运行自动格式化和代码检查

请注意，如果这些检查失败，您的工作将无法合并！运行 make help 以获取其他有用命令的列表。

另外两点需要记住：

• 如果您添加了需要测试的代码，请添加测试。
• 如果您更改了公共 API，请更新文档。

拉取请求

当您解决问题后，在 Polars 仓库中打开一个拉取请求。请遵守以下准则：

• 标题
  • 您的拉取请求标题应以一个conventional commit 标签开头。这有助于我们将您的贡献添加到更新日志的正确部分。我们使用Angular 约定。范围可以是 rust 和/或 python，具体取决于您的贡献：此标签决定哪些更新日志将包含您的更改。如果您的更改同时影响 Rust 和 Python，则省略范围。
  • 使用以大写字母开头的描述性标题。此文本将出现在更新日志中，因此请确保文本对用户有意义。使用单个反引号来注释代码片段。使用主动语态，并且标题不要以标点符号结尾。
  • 示例：fix(python): Fix `DataFrame.top_k` not handling nulls correctly
• 描述
  • 在拉取请求描述中，链接到您正在处理的 issue。
  • 在描述中添加您认为可能有助于维护者审查您的代码的任何相关信息。
• 确保您的分支已基于 main 分支的最新版本进行 rebase。
• 确保所有 GitHub Actions 检查都通过。

在您打开拉取请求后，维护者将对其进行审查并可能留下一些评论。一旦所有问题都解决，维护者将合并您的拉取请求，您的工作将成为下一个 Polars 版本的一部分！

请记住，您的工作不必立即完美！如果您遇到困难或不确定您的解决方案，请随意打开一个草稿拉取请求并寻求帮助。

贡献文档

Polars 文档最重要的组成部分是用户指南、API 参考和 StackOverflow 上的问题数据库。

用户指南

用户指南维护在 docs/source/user-guide 文件夹中。在创建 PR 之前，请先提出一个 issue，讨论您认为缺少或可以改进的地方。

构建和提供用户指南

用户指南使用 MkDocs 构建。您可以通过在仓库根目录运行 make build 来安装构建用户指南的依赖项。此外，您需要确保 graphviz 的 dot 二进制文件在您的路径中。

激活虚拟环境并运行 mkdocs serve 来构建和提供用户指南，这样您就可以在本地查看它并实时看到您所做的更改。

创建新的用户指南页面

每个用户指南页面都基于一个 .md Markdown 文件。此文件必须在 mkdocs.yml 中列出。

添加 shell 代码块

要添加一个包含将在 shell 中运行的代码块（带有 Python 和 Rust 标签），请使用以下格式：

=== ":fontawesome-brands-python: Python"

    ```shell
    $ pip install fsspec
    ```

=== ":fontawesome-brands-rust: Rust"

    ```shell
    $ cargo add aws_sdk_s3
    ```

添加代码块

Python 和 Rust 代码块的片段分别位于 docs/source/src/python/ 和 docs/source/src/rust/ 目录中。要将带有 Python 或 Rust 代码的代码片段添加到 .md 页面，请使用以下格式：

{{code_block('user-guide/io/cloud-storage','read_parquet',['read_parquet','read_csv'])}}

• 第一个参数是 docs/source/src/python/user-guide/io/cloud-storage.py 和 docs/source/src/rust/user-guide/io/cloud-storage.rs 中任意一个或两个文件的路径。
• 第二个参数是在 .py 或 .rs 文件中每个代码片段开头和结尾处给定的名称
• 第三个参数是 API 文档中函数链接的列表。列表中的每个元素都必须在 docs/source/_build/API_REFERENCE_LINKS.yml 中有一个相应的条目。

如果相应的 .py 和 .rs 代码片段文件都存在，那么上面 code_block 的第二个参数中命名的每个代码片段都必须存在，否则构建将失败。如果不需要该代码片段，应在 .py 或 .rs 文件中添加一个空的代码片段。

每个代码片段的格式如下：

import polars as pl

df = pl.read_parquet("file.parquet")

代码片段由 --8<-- [start:<snippet_name>] 和 --8<-- [end:<snippet_name>] 分隔。代码片段名称必须与上面 code_block 的第二个参数中给定的名称匹配。

在某些情况下，您可能需要为 Python 和 Rust API 添加指向不同函数的链接。在这种情况下，您可以使用 code_block 接受的两个额外可选参数，这些参数可用于传递仅限 Python 和仅限 Rust 的链接

{{code_block('path', 'snippet_name', ['common_api_links'], ['python_only_links'], ['rust_only_links'])}}

代码检查

在提交之前，安装 dprint（见上文）并从 docs 目录运行 dprint fmt 以检查 Markdown 文件。

API 参考

Polars 为 Rust 和 Python 提供独立的 API 参考。这些参考是直接从代码库生成的，因此要做出贡献，您必须遵循上面本节中概述的步骤。

Rust

Rust Polars 使用 cargo doc 来构建其文档。欢迎对 API 参考进行改进或澄清的贡献。

Python

对于 Python API 参考，我们始终欢迎良好的文档字符串示例。API 的某些部分仍然没有代码示例。这是开始为 Polars 做出贡献的好方法！

请注意，我们遵循 numpydoc 约定。文档字符串示例也应遵循 Black 代码风格。在 py-polars 目录中，运行 make fmt 以确保您的添加通过代码检查器，并运行 make doctest 以确保您的文档字符串示例有效。

Polars 使用 Sphinx 构建 API 参考。这意味着文档字符串通常应遵循 reST 格式。如果您想在本地构建 API 参考，请进入 py-polars/docs 目录并运行 make html。生成的 HTML 文件将位于 py-polars/docs/build/html。

API 的新增内容应通过在 py-polars/docs/source/reference 目录中相应的 .rst 文件中添加条目来手动添加到 API 参考中。

StackOverflow

我们使用 StackOverflow 创建一个高质量的问题和答案数据库，该数据库可搜索并保持最新。每种语言都有一个单独的标签：

• Python Polars
• Rust Polars

欢迎以精心措辞的问题或答案形式做出贡献！如果您添加了一个新问题，请通过在我们的 GitHub issue 跟踪器中添加一个匹配的 issue 来通知我们。

发布流程

本节适用于 Polars 维护者。

Polars 将 Rust crate 发布到 crates.io，并将 Python 包发布到 PyPI。

新版本通过官方 GitHub 发布和相关的 git 标签进行标记。我们利用 Release Drafter 自动草拟带有发布说明的 GitHub 发布。

步骤

发布新的 Rust 或 Python 版本的步骤相似。发布过程主要通过 GitHub Actions 自动化，但仍需要一些手动步骤。请按照以下步骤发布新版本。

首先更新源代码中的版本号

1. 检查 GitHub 上的发布页面，找到相应的草稿发布。记下与此发布关联的版本号。
2. 确保您的分叉与 Polars 主仓库的最新版本保持同步，并创建一个新分支。

3. 更新版本号。

4. Rust: 更新 polars 目录及其子目录中所有 Cargo.toml 文件中的版本号。您可能需要使用一些搜索/替换策略，因为有很多 crate 需要更新。

5. Python: 更新 py-polars/Cargo.toml 中的版本号以匹配草稿发布的版本。

6. 在 py-polars 目录中，运行 make build 以生成新的 Cargo.lock 文件。

7. 创建一个包含所有已添加文件的新提交。提交名称应遵循格式 release(<language>): <Language> Polars <version-number>。例如：release(python): Python Polars 0.16.1
8. 推送您的分支并向 Polars 主仓库的 main 分支打开一个新的拉取请求。
9. 等待 GitHub Actions 检查通过，然后合并您的拉取请求（squash and merge）。

合并拉取请求后，立即发布新版本：

1. 转到发布工作流（Python/Rust），点击右上角的“运行工作流”，然后点击绿色按钮。这将触发工作流，它将构建所有发布工件并发布它们。
2. 等待工作流完成，然后检查 crates.io/PyPI/GitHub 以验证新的 Polars 版本是否已可用。

故障排除

可能会出现一个或多个发布作业失败的情况。如果发生这种情况，您应该首先尝试直接从 GitHub Actions UI 重新运行失败的作业。

如果这没有帮助，您将不得不找出问题所在并提交修复。一旦您的修复进入 main 分支，只需重新触发发布工作流。

许可证

您对本项目所做的任何贡献都将受涵盖 Polars 项目的 MIT 许可证的约束。