概述

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

报告错误

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

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

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

建议增强功能

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

请描述您希望的行为及其原因，并提供如果添加了您的功能，Polars 将如何使用的示例。

贡献代码库

选择一个议题

通过浏览问题跟踪器并找到一个你想处理的问题来选择一个任务。随意选择任何带有已接受标签且尚未分配的问题。我们使用需要帮助标签来指示我们愿望清单上优先级较高的问题。

如果你是第一次贡献者，你可能会想寻找标记为 good first issue的问题。 Polars代码库相当复杂，所以从一个小问题开始将帮助你找到你的方向！

如果您想处理一个问题，请在问题上发表评论以告知他人。您可以使用该问题来讨论可能的解决方案。

设置本地环境

Polars 的开发流程依赖于 Rust 和 Python，这意味着设置本地开发环境并不简单。如果遇到问题，请在 Discord 上联系我们。

配置 Git

要为Polars做出贡献，你需要一个免费的GitHub账户，并且你的机器上需要安装git。首先fork Polars仓库，然后使用git克隆你fork的仓库：

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.12）。确保你停用任何活动的虚拟环境（命令：deactivate）或conda环境（命令：conda deactivate），因为下面的步骤将为Polars创建一个新的虚拟环境。即使你只打算处理Rust代码，你也需要Python，因为我们依赖Python测试来验证所有功能。

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

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

cd py-polars
make test

这将做很多事情：

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

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

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仓库中。请遵循以下指南：

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

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

请记住，你的工作不必一开始就完美！如果你卡住了或对你的解决方案不确定，随时可以打开一个草稿拉取请求并寻求帮助。

贡献文档

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

用户指南

用户指南保存在docs/source/user-guide文件夹中。在创建PR之前，请先提出一个问题来讨论您认为缺少或可以改进的内容。

构建和提供用户指南

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

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

创建新的用户指南页面

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

添加一个shell代码块

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

=== ":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:]和--8<-- [end:]界定。代码片段的名称必须与上面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问题跟踪器中添加一个匹配的问题来通知我们。

发布流程

本节适用于Polars维护者。

Polars 发布 Rust 包到 crates.io 和 Python 包到 PyPI。

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

步骤

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

首先在源代码中增加版本号：

1. 检查GitHub上的发布页面并找到适当的草稿发布。注意与此发布相关的版本号。
2. 确保你的fork与主Polars仓库的最新版本保持同步，并创建一个新的分支。

3. 提升版本号。

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

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

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

7. 创建一个包含所有文件的新提交。提交的名称应遵循格式 release(): Polars 。例如： release(python): Python Polars 0.16.1
8. 推送你的分支并打开一个新的拉取请求到主Polars仓库的main分支。
9. 等待 GitHub Actions 检查通过，然后压缩并合并您的拉取请求。

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

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

故障排除

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

如果那没有帮助，你将不得不找出问题所在并提交修复。一旦你的修复已经合并到main分支，只需重新触发发布工作流。

许可证

您对本项目的任何贡献都将适用于涵盖Polars项目的MIT许可证。