Getting Involved / Contributing¶
Ray is more than a framework for distributed applications but also an active community of developers, researchers, and folks that love machine learning.
Ask questions on our forum! The community is extremely active in helping people succeed in building their Ray applications.
You can join (and Star!) us on on GitHub.
Contributing to Ray¶
We welcome (and encourage!) all forms of contributions to Ray, including and not limited to:
Code reviewing of patches and PRs.
Documentation and examples.
Community participation in forums and issues.
Code readability and code comments to improve readability.
Test cases to make the codebase more robust.
Tutorials, blog posts, talks that promote the project.
What can I work on?¶
Setting up your development environment¶
To edit the Ray source code, you’ll want to checkout the repository and also build Ray from source. Follow these instructions for building a local copy of Ray to easily make changes.
Submitting and Merging a Contribution¶
There are a couple steps to merge a contribution.
First merge the most recent version of master into your development branch.
git remote add upstream https://github.com/ray-project/ray.git git pull . upstream/master
Make sure all existing tests pass.
If introducing a new feature or patching a bug, be sure to add new test cases in the relevant file in ray/python/ray/tests/.
Document the code. Public functions need to be documented, and remember to provide an usage example if applicable.
Request code reviews from other contributors and address their comments. During the review process you may need to address merge conflicts with other changes. To resolve merge conflicts, run
git pull . upstream/masteron your branch (please do not use rebase, as it is less friendly to the GitHub review tool. All commits will be squashed on merge.)
Reviewers will merge and approve the pull request; be sure to ping them if the pull request is getting stale.
Even though we have hooks to run unit tests automatically for each pull request, we recommend you to run unit tests locally beforehand to reduce reviewers’ burden and speedup review process.
If you are running tests for the first time, you can install the required dependencies with:
pip install -r python/requirements.txt
Testing for Python development¶
The full suite of tests is too large to run on a single machine. However, you can run individual relevant Python test files. Suppose that one of the tests in a file of tests, e.g.,
python/ray/tests/test_basic.py, is failing. You can run just that test file locally as follows:
pytest -v -s python/ray/tests/test_basic.py
This will run all of the tests in the file. To run a specific test, use the following:
pytest -v -s test_file.py::name_of_the_test
Testing for C++ development¶
To compile and run all C++ tests, you can run:
bazel test $(bazel query 'kind(cc_test, ...)')
Alternatively, you can also run one specific C++ test. You can use:
bazel test $(bazel query 'kind(cc_test, ...)') --test_filter=ClientConnectionTest --test_output=streamed
In general, we follow the Google style guide for code in C++ and Python. However, it is more important for code to be in a locally consistent style than to strictly follow guidelines. Whenever in doubt, follow the local code style of the component.
For Python documentation, we follow a subset of the Google pydoc format. The following code snippet demonstrates the canonical Ray pydoc formatting:
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: >>> # Provide code examples 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. """
Lint and Formatting¶
We also have tests for code formatting and linting that need to pass before merge.
For Python formatting, install the required dependencies first with:
pip install -r python/requirements_linters.txt
On MacOS X, don’t use HomeBrew to install
clang-format, as the only version available is too new.
You can run the following locally:
An output like the following indicates failure:
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
In addition, there are other formatting and semantic checkers for components like the following (not included in
Python README format:
cd python python setup.py check --restructuredtext --strict --metadata
clang-tidy for C++ anti-patterns, requires
clang-tidyversion 12 to be installed:
Understanding CI test jobs¶
The Ray project automatically runs continuous integration (CI) tests once a PR is opened using Buildkite with multiple CI test jobs.
The CI test folder contains all integration test scripts and they
invoke other test scripts via
bazel-based test or other bash
scripts. Some of the examples include:
- Raylet integration tests commands:
bazel test //:core_worker_test
- Bazel test command:
bazel test --build_tests_only //:all
- Ray serving test commands:
If a CI build exception doesn’t appear to be related to your change, please visit this link to check recent tests known to be flaky.
Ray provides stability guarantees for its public APIs in Ray core and libraries. The level of stability provided depends on how the API is annotated.
Annotation for documenting public APIs.
Public APIs are classes and methods exposed to end users of Ray. You can expect these APIs to remain backwards compatible across minor Ray releases (e.g., Ray 1.4 -> 1.8).
stability – Either “stable” for stable features or “beta” for APIs that are intended to be public but still in beta.
>>> @PublicAPI >>> def func(x): >>> return x
>>> @PublicAPI(stability="beta") >>> def func(y): >>> return y
Annotation for documenting developer APIs.
Developer APIs are lower-level methods explicitly exposed to advanced Ray users and library developers. Their interfaces may change across minor Ray releases.
>>> @DeveloperAPI >>> def func(x): >>> return x
Annotation for documenting a deprecated API.
Deprecated APIs may be removed in future releases of Ray.
>>> @Deprecated >>> def func(x): >>> return x
Undecorated functions can be generally assumed to not be part of the Ray public API.
API compatibility style guide¶
It’s hard to fully capture the semantics of API compatibility into a single annotation (for example, public APIs may have “experimental” arguments). For more granular stability contracts, those can be noted in the pydoc (e.g., “the
random_shuffle option is experimental”). When possible, experimental arguments should also be prefixed by underscores in Python (e.g., _owner=).
In Python APIs, consider forcing the use of kwargs instead of positional arguments (with the
* operator). Kwargs are easier to keep backwards compatible than positional arguments, e.g. imagine if you needed to deprecate “opt1” below, it’s easier with forced kwargs:
def foo_bar(file, *, opt1=x, opt2=y) pass
For callback APIs, consider adding a
**kwargs placeholder as a “forward compatibility placeholder” in case more args need to be passed to the callback in the future, e.g.:
def tune_user_callback(model, score, **future_kwargs): pass
Becoming a Reviewer¶
We identify reviewers from active contributors. Reviewers are individuals who not only actively contribute to the project and are also willing to participate in the code review of new contributions. A pull request to the project has to be reviewed by at least one reviewer in order to be merged. There is currently no formal process, but active contributors to Ray will be solicited by current reviewers.
More Resources for Getting Involved¶
Ray is more than a framework for distributed applications but also an active community of developers, researchers, and folks that love machine learning. Here’s a list of tips for getting involved with the Ray community:
Join our community Slack to discuss Ray!
Star and follow us on on GitHub.
To post questions or feature requests, check out the Discussion Board!
Follow us and spread the word on Twitter!
Join our Meetup Group to connect with others in the community!
Use the [ray] tag on StackOverflow to ask and answer questions about Ray usage
These tips are based off of the TVM contributor guide.