Skip to content

Latest commit

 

History

History
199 lines (136 loc) · 6.47 KB

CONTRIBUTING.md

File metadata and controls

199 lines (136 loc) · 6.47 KB
Raw

How to contribute code

Follow these steps to submit your code contribution.

Step 1. Open an issue

Before making any changes, we recommend opening an issue (if one doesn't already exist) and discussing your proposed changes. This way, we can give you feedback and validate the proposed changes.

If the changes are minor (simple bug fix or documentation fix), then feel free to open a PR without discussion.

Step 2. Make code changes

To make code changes, you need to fork the repository. You will need to setup a development environment and run the unit tests. This is covered in the section "Setup environment".

Step 3. Create a pull request

Once the change is ready, open a pull request from your branch in your fork to the master branch in keras-team/keras.

Step 4. Sign the Contributor License Agreement

After creating the pull request, the cla/google check will be performed and, if you haven't signed the Contributor License Agreement (CLA), it will fail with instructions on how to do so. Please follow the instructions to sign the CLA and the check will pass.

CLA signed

Step 5. Code review

If the tests fail, look into the error messages and try to fix them.

CI tests

A reviewer will review the pull request and provide comments. There may be several rounds of comments and code changes before the pull request gets approved by the reviewer.

Approval from reviewer

Step 6. Merging

Once the pull request is approved, a ready to pull tag will be added to the pull request. A team member will take care of the merging.

Ready to pull and merged

Here is an example pull request for your reference.

Setup environment

We provide two ways of setting up a development environment. One is to use a dev container, and the other one is to setup a local environment by installing the dev tools needed.

Option 1: GitHub Codespace or dev container

We support GitHub Codespaces, Visual Studio Code dev containers and JetBrain dev containers. Please see the Dev container documentation.

Option 2: Setup a local environment

To setup your local dev environment, you will need the following tools.

  1. git for code repository management.
  2. python to build and code in Keras.

The following commands check the tools above are successfully installed. Note that Keras requires at least Python 3.9 to run.

git --version
python --version

Clone your forked repo to your local machine. Go to the cloned directory to install the dependencies.

git clone https://github.com/YOUR_GITHUB_USERNAME/keras.git
cd keras
pip install -r requirements.txt

You then need to configure the backend to use, see the Configuring your backend section of the README.

You can also add GPU support to your environment, see the Adding GPU support section of the README.

Code style

The Keras uses Black and isort to format the code. Please refer to requirements-common.txt for the required versions. Run the following command at the root directory of the repo to format your code.

sh shell/format.sh

It will also display the errors that cannot be resolved by autoformatting. You need to follow the output of the command to resolve them manually.

If you do not want to auto format the code but only show the lint errors, you can run sh shell/lint.sh at the root directory of the repo.

Docstrings

We do not have an automated way to check docstring style, so if you write or edit any docstring, please make sure to check them manually. Keras docstrings follow the conventions below:

A class docstring may contain the following items:

  • A one-line description of the class.
  • Paragraph(s) of more detailed information.
  • Optional Examples section.
  • Args section for arguments in __init__().
  • If it's a layer:
    • Call arguments section for arguments in Layer.call().
    • Returns section for the return values of Layer.call().
    • Optional Raises section for possible errors.

You can check out MultiHeadAttention as an example (link).

A function docstring may contain the following items:

  • One-line description of the function.
  • Paragraph(s) of more detailed information.
  • Optional Examples section.
  • Args section for the function arguments.
  • Returns section for the return values.
  • Optional Raises section for possible errors.

You can check out text_dataset_from_directory as an example (link).

Run tests

We use pytest to run the tests.

Run a test file

To run the tests in pytest keras/losses/losses_test.py, use following command at the root directory of the repo.

pytest pytest keras/losses/losses_test.py

Run a single test case

You can specify a single test class to run within a file.

pytest keras/losses/losses_test.py::MeanSquaredErrorTest

You can also specify a single test method to run within a class.

pytest keras/losses/losses_test.py::MeanSquaredErrorTest::test_sample_weighted

Run all tests

You can run all the tests locally by running the following command in the repo root directory.

pytest keras

Note that you can skip the Keras applications tests using the SKIP_APPLICATIONS_TESTS environment variable. This will cut down the testing time significantly.

SKIP_APPLICATIONS_TESTS=True pytest keras

To run all tests using a different backend, you can simply specify it on the command line.

KERAS_BACKEND=jax SKIP_APPLICATIONS_TESTS=True pytest keras