贡献指南#

如果您希望您的更改能够快速得到审查和合并，遵循一些关键实践会产生巨大影响。清晰、专注且结构良好的贡献有助于审查者理解您的意图，并确保您的改进顺利落地。

另请参阅

本指南专门涵盖向 Ray Data 贡献。有关向 Ray 项目总体贡献的信息，请参阅通用的 Ray 贡献指南。

寻找可以着手的工作#

首先解决您遇到的问题，例如修复 bug 或添加缺失的功能。如果您不确定从哪里开始

  • 浏览问题跟踪器，寻找您理解的问题。

  • 寻找诸如“good first issue”之类的标签，以找到易于上手的任务。

  • 加入 Ray Slack，并在 #data-contributors 频道发帖。

获取早期反馈#

如果您正在添加新的公共 API 或进行实质性的重构，请**尽早分享您的计划**。在投入大量工作之前讨论更改可以节省时间，并使您的工作与项目方向保持一致。

您可以打开一个草稿 PR、在 Issue 上讨论，或者在 Slack 上发帖以获取早期反馈。这不会影响接受度，并且通常会改进最终设计。

编写良好的测试#

Ray Data 的大多数更改都需要测试。有关如何编写良好测试的技巧，请参阅如何编写测试。

编写简洁、清晰的代码#

Ray Data 重视**可读、可维护且可扩展**的代码，而非巧妙的技巧。有关如何编写符合 Ray Data 设计品味的指南，请参阅《软件设计哲学》。

在本地测试您的更改#

要在本地测试您的更改，请从源代码构建 Ray。对于 Ray Data 的开发，您通常只需要 Python 环境——除非您也为 Ray Core 做贡献，否则可以跳过 C++ 构建。

在提交 PR 之前，运行 pre-commit 来格式化您的更改，并运行 pytest 来执行您的测试。

请注意，完整的 Ray Data 测试套件在本地运行可能会很耗时，请从与您的更改直接相关的测试开始。例如，如果您修改了 map 函数，从 python/ray/data/tests 目录运行：pytest test_map.py。

打开一个 Pull Request#

编写清晰的 Pull Request 描述#

解释**更改的原因和实现的功能**。清晰的描述可以减少来回沟通，加快审查速度。

以下是一个具有良好描述的 PR 示例：[Data] Refactor PhysicalOperator.completed to fix side effects （[Data] 重构 PhysicalOperator.completed 以修复副作用）。

保持 Pull Request 简洁#

审查难度与 PR 大小的关系是非线性的。

为了快速审查，请执行以下操作

  • 尽可能将 PR 的更改控制在**200 行以内**。

  • **拆分大型 PR** 为多个增量 PR。

  • 避免在同一 PR 中混合重构和新功能。

以下是一个保持范围小的 PR 示例：[Data] Support Non-String Items for ApproximateTopK Aggregator（[Data] 为 ApproximateTopK 聚合器支持非字符串项）。尽管更广泛的工作集中在优化预处理器上，但这项更改被特意拆分出来作为一个小的、增量的 PR，这使得它更容易审查。

让 CI 通过#

Ray 的 CI 首先在 buildkite/microcheck 检查中运行代码格式化和一小组测试。首先确保它通过。

一旦它通过（绿色），请标记您的审查者。他们可以添加 go 标签来触发完整的测试套件。