检查您的版本！

事情变化很快，这份贡献者指南也是如此。为了确保您拥有最新版本的指南，请查看最新版本。

参与 / 贡献#

Ray 不仅是一个分布式应用框架，也是一个由开发者、研究人员以及热爱机器学习的人们组成的活跃社区。

提示

请在我们的论坛上提问！社区非常活跃，乐于帮助人们成功构建 Ray 应用。

您可以在 GitHub 上加入我们（并点赞！）。

贡献 Ray#

我们欢迎（并鼓励！）所有形式对 Ray 的贡献，包括但不限于

  • 代码审查补丁和 PR。

  • 提交补丁。

  • 文档和示例。

  • 在论坛和 issue 中参与社区活动。

  • 提高代码可读性的代码可读性和代码注释。

  • 编写测试用例使代码库更健壮。

  • 推广项目的教程、博客文章、讲座。

  • 通过 Ray 增强提案 (REP) 实现功能和重大更改：ray-project/enhancements

我可以做什么？#

我们使用 Github 跟踪问题、功能请求和 bug。请查看标有 “good first issue” 的问题，这是一个很好的开始。

设置您的开发环境#

要编辑 Ray 源代码，请 fork 仓库，克隆它，然后从源码构建 Ray。请遵循这些构建说明来构建 Ray 的本地副本，以便轻松进行更改。

提交和合并贡献#

合并贡献有几个步骤。

  1. 首先将 master 的最新版本合并到您的开发分支中。

    git remote add upstream https://github.com/ray-project/ray.git
git pull . upstream/master

  2. 确保所有现有的测试和linter都通过。运行 setup_hooks.sh 创建一个 git hook，它将在您 push 更改之前运行 linter。

  3. 如果引入新功能或修补 bug，请务必在 ray/python/ray/tests/ 目录中的相关文件中添加新的测试用例。

  4. 记录代码。公共函数需要文档，如果适用，请记住提供使用示例。有关编辑和构建公共文档的说明，请参阅 doc/README.md。

  5. 解决 PR 上的评论。在审查过程中，您可能需要解决与其他更改的合并冲突。要解决合并冲突，请在您的分支上运行 git pull . upstream/master（请不要使用 rebase，因为它对 GitHub 审查工具不太友好。所有 commit 在合并时都会被 squash）。

  6. 审查者将合并并批准 pull request；如果 pull request 变得陈旧，请务必 ping 他们。

PR 审查流程#

对于 ray-project 组织内的贡献者：#

  • 当您首次创建 PR 时，将审查者添加到 assignee 部分。

  • 被指派者将审查您的 PR，如果需要进一步操作，将添加 @author-action-required 标签。

  • 解决他们的评论并从 PR 中删除 @author-action-required 标签。

  • 重复此过程，直到被指派者批准您的 PR。

  • PR 批准后，作者负责确保 PR 通过构建。如果构建成功，请添加 test-ok 标签。

  • 一旦构建通过，提交者将合并 PR。

对于不在 ray-project 组织内的贡献者：#

  • 您的 PR 很快就会有被指派者。PR 的被指派者将积极与贡献者沟通以合并 PR。

  • 在您解决评论后，请积极 ping 被指派者！

测试#

尽管我们有 hook 可以自动为每个 pull request 运行单元测试，但我们建议您事先在本地运行单元测试，以减轻审查者的负担并加速审查过程。

如果您是第一次运行测试，可以使用以下命令安装所需的依赖项

pip install -c python/requirements_compiled.txt -r python/requirements/test-requirements.txt

Python 开发测试#

完整的测试套件太大，无法在单台机器上运行。但是，您可以运行单个相关的 Python 测试文件。假设测试文件中的某个测试（例如 python/ray/tests/test_basic.py 中的一个测试）失败了。您可以在本地仅运行该测试文件，如下所示

# Directly calling `pytest -v ...` may lose import paths.
python -m pytest -v -s python/ray/tests/test_basic.py

这将运行文件中的所有测试。要运行特定测试，请使用以下命令

# Directly calling `pytest -v ...` may lose import paths.
python -m pytest -v -s test_file.py::name_of_the_test

C++ 开发测试#

要编译并运行所有 C++ 测试，您可以运行

bazel test $(bazel query 'kind(cc_test, ...)')

或者，您也可以运行一个特定的 C++ 测试。您可以使用

bazel test $(bazel query 'kind(cc_test, ...)') --test_filter=ClientConnectionTest --test_output=streamed

代码风格#

一般来说，我们遵循 Google C++ 代码风格指南 和 Black Python 代码风格。Python 导入遵循 PEP8 风格。然而，代码保持本地一致风格比严格遵循指南更重要。如有疑问，请遵循组件的本地代码风格。

对于 Python 文档，我们遵循 Google pydoc 格式 的一个子集。以下代码片段演示了标准的 Ray pydoc 格式

def ray_canonical_doc_style(param1: int, param2: str) -> bool:
    """First sentence MUST be inline with the quotes and fit on one line.

    Additional explanatory text can be added in paragraphs such as this one.
    Do not introduce multi-line first sentences.

    Examples:
        .. doctest::

            >>> # Provide code examples for key use cases, as possible.
            >>> ray_canonical_doc_style(41, "hello")
            True

            >>> # A second example.
            >>> ray_canonical_doc_style(72, "goodbye")
            False

    Args:
        param1: The first parameter. Do not include the types in the
            docstring. They should be defined only in the signature.
            Multi-line parameter docs should be indented by four spaces.
        param2: The second parameter.

    Returns:
        The return value. Do not include types here.
    """

class RayClass:
    """The summary line for a class docstring should fit on one line.

    Additional explanatory text can be added in paragraphs such as this one.
    Do not introduce multi-line first sentences.

    The __init__ method is documented here in the class level docstring.

    All the public methods and attributes should have docstrings.

    Examples:
        .. testcode::

            obj = RayClass(12, "world")
            obj.increment_attr1()

    Args:
        param1: The first parameter. Do not include the types in the
            docstring. They should be defined only in the signature.
            Multi-line parameter docs should be indented by four spaces.
        param2: The second parameter.
    """

    def __init__(self, param1: int, param2: str):
        #: Public attribute is documented here.
        self.attr1 = param1
        #: Public attribute is documented here.
        self.attr2 = param2

    @property
    def attr3(self) -> str:
        """Public property of the class.

        Properties created with the @property decorator
        should be documented here.
        """
        return "hello"

    def increment_attr1(self) -> None:
        """Class methods are similar to regular functions.

        See above about how to document functions.
        """

        self.attr1 = self.attr1 + 1

有关如何在 docstrings 中编写代码片段的更多详细信息，请参阅此处。

Lint 和格式化#

我们还有代码格式化和 linting 测试，必须通过后才能合并。

pip install -c python/requirements_compiled.txt -r python/requirements/lint-requirements.txt

  • 如果是进行 C++ 开发，您将需要 clang-format 版本 12（可从此处下载此版本的 Clang）

您可以在本地运行以下命令

pip install -U pre-commit==3.5.0
pre-commit install  # automatic checks before committing
pre-commit run ruff -a

如下所示的输出表示失败

WARNING: clang-format is not installed!  # This is harmless
From https://github.com/ray-project/ray
 * branch                master     -> FETCH_HEAD
python/ray/util/sgd/tf/tf_runner.py:4:1: F401 'numpy as np' imported but unused  # Below is the failure

此外，还有针对以下组件的其他格式化和语义检查器（不包含在 scripts/format.sh 中）

  • Python README 格式

cd python
python setup.py check --restructuredtext --strict --metadata

  • Python & Docs 禁用词检查

./ci/lint/check-banned-words.sh

  • Bazel 格式化

./ci/lint/bazel-format.sh

  • 用于 C++ lint 的 clang-tidy，需要安装 clang 和 clang-tidy 版本 12

./ci/lint/check-git-clang-tidy-output.sh

理解 CI 测试作业#

Ray 项目在使用 Buildkite 开启 PR 后，会自动运行持续集成 (CI) 测试，包含多个 CI 测试作业。

的CI测试文件夹包含所有集成测试脚本，它们通过pytest、基于bazel的测试或其他 bash 脚本调用其他测试脚本。一些示例包括

  • Bazel 测试命令

    • bazel test --build_tests_only //:all

  • Ray Serve 测试命令

    • pytest python/ray/serve/tests

    • python python/ray/serve/examples/echo_full.py

如果 CI 构建异常似乎与您的更改无关，请访问此链接查看已知不稳定的最新测试。

API 兼容性风格指南#

Ray 为其在 Ray core 和库中的公共 API 提供稳定性保证，具体描述请参见API 稳定性指南。

很难将 API 兼容性的语义完全用一个注解表达出来（例如，公共 API 可能有“实验性”参数）。对于更细粒度的稳定性契约，可以在 pydoc 中注明（例如，“random_shuffle 选项是实验性的”）。如果可能，实验性参数在 Python 中也应该以划线开头（例如，_owner=）。

其他建议:

在 Python API 中，考虑强制使用 kwargs 而不是位置参数（使用 * 运算符）。kwargs 比位置参数更容易保持向后兼容性，例如，想象一下如果需要弃用下面的“opt1”，使用强制 kwargs 会更容易

def foo_bar(file, *, opt1=x, opt2=y)
    pass

对于回调 API，可以考虑添加一个 **kwargs 占位符作为“向前兼容性占位符”，以防将来需要向回调传递更多参数，例如

def tune_user_callback(model, score, **future_kwargs):
    pass

社区示例#

我们一直在寻找新的示例贡献！当为 Ray 库贡献示例时，请在该库的 examples.yml 文件中包含您的示例链接

- title: Serve a Java App
  skill_level: advanced
  link: tutorials/java
  contributor: community

为您的示例提供一个标题、一个技能水平（beginner、intermediate 或 advanced）和一个链接（相对链接指向其他文档页面，但以 http:// 开头的直接链接也有效）。包含 contributor: community 元数据，以确保示例在示例集中被正确标记为社区示例。

成为审查者#

我们从活跃的贡献者中识别审查者。审查者是不仅积极贡献项目，而且愿意参与新贡献的代码审查的个人。项目的 pull request 必须由至少一名审查者审查才能合并。目前没有正式流程，但 Ray 的活跃贡献者将由现有审查者征集。

更多参与资源#

Ray 不仅是一个分布式应用框架，也是一个由开发者、研究人员以及热爱机器学习的人们组成的活跃社区。以下是参与 Ray 社区的一些提示列表

  • 加入我们的社区 Slack 来讨论 Ray！

  • 在 GitHub 上收藏并关注我们。

  • 要提交问题或功能请求，请查看讨论区！

  • 在 Twitter 上关注我们并传播信息！

  • 加入我们的 Meetup 小组，与社区中的其他人联系！

  • 在 StackOverflow 上使用 [ray] 标签提问和回答关于 Ray 使用的问题

注意

这些提示基于 TVM 贡献者指南。