From ba83ab5d3bfe652e0ed9d1c836b258327726f405 Mon Sep 17 00:00:00 2001 From: Jake VanderPlas Date: Tue, 27 Apr 2021 15:00:21 -0700 Subject: [PATCH] Add expanded contributing documentation --- CONTRIBUTING.md | 27 +------ docs/contributing.md | 165 +++++++++++++++++++++++++++++++++++++++++++ docs/developer.md | 4 ++ docs/index.rst | 1 + 4 files changed, 173 insertions(+), 24 deletions(-) create mode 100644 docs/contributing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3ecc90e9b..314d4387a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,25 +1,4 @@ -# How to contribute +# Contributing to JAX -## Single-change commits and pull requests - -A git commit ought to be a self-contained, single change with a descriptive -message. This helps with review and with identifying or reverting changes if -issues are uncovered later on. - -**Pull requests typically comprise a single git commit.** (In some cases, for -instance for large refactors or internal rewrites, they may contain several.) -In preparing a pull request for review, you may need to squash together -multiple commits. We ask that you do this prior to sending the PR for review if -possible. The `git rebase -i` command might be useful to this end. - -## Contributor license agreement (CLA) - -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted -one (even if it was for a different project), you probably don't need to do it -again. +For information on how to contribute to JAX, see +[Contributing to JAX](https://jax.readthedocs.io/en/latest/contributing.html) diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 000000000..5c6dc4947 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,165 @@ +# Contributing to JAX + +Everyone can contribute to JAX, and we value everyone's contributions. There are several +ways to contribute, including: + +- Answering questions on JAX's [discussions page](https://github.com/google/jax/discussions) +- Improving or expanding JAX's [documentation](http://jax.readthedocs.io/) +- Contributing to JAX's [code-base](http://github.com/google/jax/) +- Contributing in any of the above ways to the broader ecosystem of [libraries built on JAX](https://github.com/google/jax#neural-network-libraries) + +The JAX project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/). + +## Ways to contribute + +We welcome pull requests, in particular for those issues marked with +[contributions welcome](https://github.com/google/jax/issues?q=is%3Aopen+is%3Aissue+label%3A%22contributions+welcome%22) or +[good first issue](https://github.com/google/jax/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). + +For other proposals, we ask that you first open a GitHub +[Issue](https://github.com/google/jax/issues/new/choose) or +[Discussion](https://github.com/google/jax/discussions) +to seek feedback on your planned contribution. + +## Contributing code using pull requests + +We do all of our development using git, so basic knowledge is assumed. + +Follow these steps to contribute code: + +1. Fork the JAX repository by clicking the **Fork** button on the + [repository page](http://www.github.com/google/jax). This creates + a copy of the JAX repository in your own account. + +2. Install Python >=3.6 locally in order to run tests. + +3. `pip` installing your fork from source. This allows you to modify the code + and immediately test it out: + + ```bash + git clone https://github.com/YOUR_USERNAME/jax + cd jax + pip install -r requirements.txt # Installs all testing requirements. + pip install -e . # Installs JAX from the current directory in editable mode. + ``` + +4. Add the JAX repo as an upstream remote, so you can use it to sync your + changes. + + ```bash + git remote add upstream http://www.github.com/google/jax + ``` + +5. Create a branch where you will develop from: + + ```bash + git checkout -b name-of-change + ``` + + And implement your changes using your favorite editor (we recommend + [Visual Studio Code](https://code.visualstudio.com/)). + +6. Make sure the tests pass by running the following command from the top of + the repository: + + ```bash + pytest -n auto tests/ + ``` + + JAX's test suite is quite large, so if you know the specific test file that covers your + changes, you can limit the tests to that; for example: + + ```bash + pytest -n auto tests/lax_scipy_test.py + ``` + + JAX also offers more fine-grained control over which particular tests are run; + see {ref}`running-tests` for more information. + +7. Once you are satisfied with your change, create a commit as follows ( + [how to write a commit message](https://chris.beams.io/posts/git-commit/)): + + ```bash + git add file1.py file2.py ... + git commit -m "Your commit message" + ``` + + Then sync your code with the main repo: + + ```bash + git fetch upstream + git rebase upstream/master + ``` + + Finally, push your commit on your development branch and create a remote + branch in your fork that you can use to create a pull request from: + + ```bash + git push --set-upstream origin name-of-change + ``` + +8. Create a pull request from the JAX repository and send it for review. + Check the {ref}`pr-checklist` for considerations when preparing your PR, and + consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) + if you need more information on using pull requests. + +(pr-checklist)= + +## JAX pull request checklist + +As you prepare a JAX pull request, here are a few things to keep in mind: + +### Google contributor license agreement + +Contributions to this project must be accompanied by a Google Contributor License +Agreement (CLA). You (or your employer) retain the copyright to your contribution; +this simply gives us permission to use and redistribute your contributions as +part of the project. Head over to to see +your current agreements on file or to sign a new one. + +You generally only need to submit a CLA once, so if you've already submitted one +(even if it was for a different project), you probably don't need to do it +again. If you're not certain whether you've signed a CLA, you can open your PR +and our friendly CI bot will check for you. + +### Single-change commits and pull requests + +A git commit ought to be a self-contained, single change with a descriptive +message. This helps with review and with identifying or reverting changes if +issues are uncovered later on. + +**Pull requests typically comprise a single git commit.** (In some cases, for +instance for large refactors or internal rewrites, they may contain several.) +In preparing a pull request for review, you may need to squash together +multiple commits. We ask that you do this prior to sending the PR for review if +possible. The `git rebase -i` command might be useful to this end. + +### Linting and Type-checking + +JAX uses [mypy](https://mypy.readthedocs.io/) and [flake8](https://flake8.pycqa.org/) +to statically test code quality; the easiest way to run these checks locally is via +the [pre-commit](https://pre-commit.com/) framework: + +```bash +pip install pre-commit +pre-commit run --all +``` + +If your pull request touches documentation notebooks, this will also run some checks +on those (See {ref}`update-notebooks` for more details). + +### Full GitHub test suite + +Your PR will automatically be run through a full test suite on GitHub CI, which +covers a range of Python versions, dependency versions, and configuration options. +It's normal for these tests to turn up failures that you didn't catch locally; to +fix the issues you can push new commits to your branch. + +### Restricted test suite + +Once your PR has been reviewed, a JAX maintainer will mark it as `Pull Ready`. This +will trigger a larger set of tests, including tests on GPU and TPU backends that are +not available via standard GitHub CI. Detailed results of these tests are not publicly +viweable, but the JAX mantainer assigned to your PR will communicate with you regarding +any failures these might uncover; it's not uncommon, for example, that numerical tests +need different tolerances on TPU than on CPU. diff --git a/docs/developer.md b/docs/developer.md index 224074c94..1c8a61097 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -125,6 +125,8 @@ repository root, and rebuild by running `build.py` or upgrading `jaxlib` if necessary. You shouldn't have to reinstall `jax` because `pip install -e` sets up symbolic links from site-packages into the repository. +(running-tests)= + # Running the tests To run all the JAX tests, we recommend using `pytest-xdist`, which can run tests in @@ -209,6 +211,8 @@ sphinx-build -b html -D jupyter_execute_notebooks=off docs docs/build/html ``` You can then see the generated documentation in `docs/build/html/index.html`. +(update-notebooks)= + ## Update notebooks We use [jupytext](https://jupytext.readthedocs.io/) to maintain two synced copies of the notebooks diff --git a/docs/index.rst b/docs/index.rst index e570a8872..8534e603f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,6 +65,7 @@ parallelize, Just-In-Time compile to GPU/TPU, and more. :maxdepth: 2 :caption: Developer documentation + contributing developer jax_internal_api autodidax