检查你的版本！

事情可以迅速变化，这份贡献者指南也是如此。为了确保你拥有这份指南的最新版本，请查看 最新版本。

参与 / 贡献#

Ray 不仅仅是一个分布式应用的框架，还是一个活跃的开发者、研究人员和热爱机器学习的社区。

小技巧

在 我们的论坛 上提问！社区在帮助人们成功构建他们的 Ray 应用程序方面非常活跃。

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

为 Ray 贡献#

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

  • 代码审查补丁和PR。

  • 推送补丁。

  • 文档和示例。

  • 社区在论坛和问题中的参与。

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

  • 测试用例以使代码库更加健壮。

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

  • 通过 Ray 增强提案 (REP) 的功能和主要变化：ray-project/enhancements

我可以做什么？#

我们使用 Github 来跟踪问题、功能请求和错误。查看标记为 “good first issue” 的问题，作为开始的地方。

设置你的开发环境#

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

提交和合并贡献#

合并贡献有几个步骤。

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

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

  2. 确保所有现有的 测试 和 代码检查工具 通过。运行 setup_hooks.sh 来创建一个 git 钩子，该钩子会在你推送更改前运行代码检查工具。

  3. 如果引入新功能或修复错误，请确保在 ray/python/ray/tests/ 中的相关文件中添加新的测试用例。

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

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

  6. 评审者将合并并批准拉取请求；如果拉取请求变得陈旧，请务必通知他们。

PR 审核流程#

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

  • 当你第一次创建一个PR时，在 assignee 部分添加一个审阅者。

  • 审核人员将审查您的PR，并在需要进一步操作时添加 @author-action-required 标签。

  • 处理他们的评论并从PR中移除 @author-action-required 标签。

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

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

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

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

  • 您的PR将很快被分配负责人。PR的负责人将积极与贡献者互动以合并PR。

  • 请在处理完您的评论后，主动提醒被指派人！

测试#

尽管我们有钩子可以自动为每个拉取请求运行单元测试，但我们建议您在本地事先运行单元测试，以减轻评审人员的负担并加快评审过程。

如果你是第一次运行测试，你可以通过以下命令安装所需的依赖项：

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

有关如何在文档字符串中编写代码片段的更多详细信息，请参阅 此。

Lint 和 格式化#

我们还有代码格式化和静态检查的测试，这些测试需要在合并之前通过。

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

  • 如果为C++开发，你需要 clang-format 版本 12 （从 这里 下载这个版本的Clang）

你可以在本地运行以下内容：

scripts/format.sh

如下所示的输出表示失败：

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 & 文档禁用词检查

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

  • Bazel 格式：

./ci/lint/bazel-format.sh

  • C++ 的 clang-tidy 用于代码检查，需要安装 clang 和 clang-tidy 版本 12：

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

你可以运行 setup_hooks.sh 来创建一个 git 钩子，该钩子会在你推送更改之前运行 linter。

理解CI测试任务#

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

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

  • Bazel 测试命令：

    • bazel test --build_tests_only //:all

  • Ray 服务测试命令：

    • pytest python/ray/serve/tests

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

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

API 兼容性风格指南#

Ray 为其 Ray 核心和库的公共 API 提供了稳定性保证，这些保证在 API 稳定性指南 中有描述。

很难将API兼容性的语义完全捕捉到一个单一的注解中（例如，公共API可能会有“实验性”参数）。为了更细粒度的稳定性合约，这些可以在pydoc中注明（例如，“``random_shuffle``选项是实验性的”）。如果可能，实验性参数在Python中也应以前缀下划线命名（例如，_owner=）。

其他建议:

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

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 元数据，以确保该示例在示例库中被正确标记为社区示例。

成为一名评审员#

我们从活跃贡献者中识别评审者。评审者不仅积极为项目做出贡献，还愿意参与新贡献的代码审查。项目的拉取请求必须至少由一名评审者审查才能合并。目前没有正式流程，但当前评审者会邀请Ray的活跃贡献者参与。

更多参与资源#

Ray 不仅仅是一个分布式应用的框架，还是一个活跃的开发者、研究人员和热爱机器学习的人们的社区。以下是一些参与 Ray 社区的建议：

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

  • 在 on GitHub 上关注我们。

  • 要发布问题或功能请求，请查看 讨论板!

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

  • 加入我们的 Meetup Group 以与社区中的其他人建立联系！

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

备注

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