mirror of
https://github.com/vale981/ray
synced 2025-03-06 10:31:39 -05:00
2702b15b04
* Add requirements-dev.txt and update docs. * Update doc/source/tune-contrib.rst Co-Authored-By: Richard Liaw <rliaw@berkeley.edu> * Unpin everything except for yapf.
117 lines
5.1 KiB
ReStructuredText
117 lines
5.1 KiB
ReStructuredText
Contributing to Tune
|
||
====================
|
||
|
||
We welcome (and encourage!) all forms of contributions to Tune, including and not limited to:
|
||
|
||
- Code reviewing of patches and PRs.
|
||
- Pushing patches.
|
||
- 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.
|
||
|
||
|
||
Setting up a development environment
|
||
------------------------------------
|
||
|
||
If you have Ray installed via pip (``pip install -U [link to wheel]`` - you can find the link to the latest wheel `here <https://ray.readthedocs.io/en/latest/installation.html>`__), you can develop Tune locally without needing to compile Ray.
|
||
|
||
First, you will need your own `fork <https://help.github.com/en/articles/fork-a-repo>`__ to work on the code. Press the Fork button on the `ray project page <https://github.com/ray-project/ray/>`__.
|
||
Then, clone the project to your machine and connect your repository to the upstream (main project) ray repository.
|
||
|
||
.. code-block:: shell
|
||
|
||
git clone https://github.com/[your username]/ray.git [path to ray directory]
|
||
cd [path to ray directory]
|
||
git remote add upstream https://github.com/ray-project/ray.git
|
||
|
||
|
||
Before continuing, make sure that your git branch is in sync with the installed Ray binaries (i.e., you are up-to-date on `master <https://github.com/ray-project/ray>`__ and have the latest `wheel <https://ray.readthedocs.io/en/latest/installation.html>`__ installed.)
|
||
|
||
Then, run `[path to ray directory]/python/ray/setup-dev.py` `(also here on Github) <https://github.com/ray-project/ray/blob/master/python/ray/setup-dev.py>`__ script.
|
||
This sets up links between the ``tune`` dir (among other directories) in your local repo and the one bundled with the ``ray`` package.
|
||
|
||
As a last step make sure to install all packages required for development of tune. This can be done by running:
|
||
|
||
.. code-block:: shell
|
||
|
||
pip install -r [path to ray directory]/python/ray/tune/requirements-dev.txt
|
||
|
||
|
||
What can I work on?
|
||
-------------------
|
||
|
||
We use Github to track issues, feature requests, and bugs. Take a look at the
|
||
ones labeled `"good first issue" <https://github.com/ray-project/ray/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22>`__ and `"help wanted" <https://github.com/ray-project/ray/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22>`__ for a place to start. Look for issues with "[tune]" in the title.
|
||
|
||
.. note::
|
||
|
||
If raising a new issue or PR related to Tune, be sure to include "[tune]" in the beginning of the title.
|
||
|
||
For project organization, Tune maintains a relatively up-to-date organization of
|
||
issues on the `Tune Github Project Board <https://github.com/ray-project/ray/projects/4>`__.
|
||
Here, you can track and identify how issues are organized.
|
||
|
||
|
||
Submitting and Merging a Contribution
|
||
-------------------------------------
|
||
|
||
There are a couple steps to merge a contribution.
|
||
|
||
1. First rebase your development branch on the most recent version of master.
|
||
|
||
.. code:: bash
|
||
|
||
git remote add upstream https://github.com/ray-project/ray.git
|
||
git fetch upstream
|
||
git rebase upstream/master
|
||
|
||
2. Make sure all existing tests `pass <tune-contrib.html#testing>`__.
|
||
3. If introducing a new feature or patching a bug, be sure to add new test cases
|
||
in the relevant file in `tune/tests/`.
|
||
4. Document the code. Public functions need to be documented, and remember to provide an usage
|
||
example if applicable.
|
||
5. Request code reviews from other contributors and address their comments. One fast way to get reviews is
|
||
to help review others' code so that they return the favor. You should aim to improve the code as much as
|
||
possible before the review. We highly value patches that can get in without extensive reviews.
|
||
6. Reviewers will merge and approve the pull request; be sure to ping them if
|
||
the pull request is getting stale.
|
||
|
||
|
||
Testing
|
||
-------
|
||
|
||
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.
|
||
|
||
|
||
.. code-block:: shell
|
||
|
||
pytest ray/python/ray/tune/tests/
|
||
|
||
Documentation should be documented in `Google style <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__ format.
|
||
|
||
We also have tests for code formatting and linting that need to pass before merge.
|
||
Install `yapf==0.23, flake8, flake8-quotes` (these are also in the `requirements-dev.txt` found in ``python/ray/tune``). You can run the following locally:
|
||
|
||
.. code-block:: shell
|
||
|
||
ray/scripts/format.sh
|
||
|
||
|
||
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 Tune will be
|
||
solicited by current reviewers.
|
||
|
||
|
||
.. note::
|
||
|
||
These tips are based off of the TVM `contributor guide <https://github.com/dmlc/tvm>`__.
|