Skip to content

Latest commit

 

History

History
216 lines (153 loc) · 7.26 KB

CONTRIBUTING.md

File metadata and controls

216 lines (153 loc) · 7.26 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 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 google-cla bot will comment on your pull request with instructions on signing the Contributor License Agreement (CLA) if you haven't done so. Please follow the instructions to sign the CLA. A cla:yes tag is then added to the pull request.

Tag added

Step 5. Code review

A reviewer will review the pull request and provide comments. The reviewer may add a kokoro:force-run label to trigger the continuous integration tests.

CI tests tag

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

CI tests

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

Here is an example pull request for your reference.

Setup environment

To setup the development environment, We provide two options. One is to use our Dockerfile, which builds into a container the required dev tools. Another one is to setup a local environment by install the dev tools needed.

Option 1: Use a Docker container

We provide a Dockerfile to build the dev environment. You can build the Dockerfile into a Docker image named keras-dev with the following command at the root directory of your cloned repo.

docker build -t keras-dev .devcontainer

You can launch a Docker container from the image with the following command. The -it option gives you an interactive shell of the container. The -v path/to/repo/:/home/keras/ mounts your cloned repo to the container. Replace path/to/repo with the path to your cloned repo directory.

docker run -it -v path/to/repo/:/home/keras/ keras-dev

In the container shell, you need to install the latest dependencies with the following command.

pip install -r /home/keras/requirements.txt

Now, the environment setup is complete. You are ready to run the tests.

You may modify the Dockerfile to your specific needs, like installing your own dev tools. You may also mount more volumes with the -v option, like your SSH credentials. Besides the editors running in the shell, many popular IDEs today also support developing in a container. You may use these IDEs with the Dockerfile as well.

Option 2: Setup a local environment

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

  1. Bazel is the tool to build and test Keras. See the installation guide for how to install and config bazel for your local environment.
  2. git for code repository management.
  3. python to build and code in Keras.

Using Apple Mac as an example (and linux will be very similar), the following commands set up and check the configuration of a local workspace.

scottzhu-macbookpro2:~ scottzhu$ which bazel
/Users/scottzhu/bin/bazel

scottzhu-macbookpro2:~ scottzhu$ which git
/usr/local/git/current/bin/git

scottzhu-macbookpro2:~ scottzhu$ which python
/usr/bin/python

# Keras requires at least python 3.7
scottzhu-macbookpro2:~ scottzhu$ python --version
Python 3.9.6

A Python virtual environment is a powerful tool to create a self-contained environment that isolates any change from the system level config. It is highly recommended to avoid any unexpected dependency or version issue.

scottzhu-macbookpro2:workspace scottzhu$ git clone https://github.com/keras-team/keras.git
Cloning into 'keras'...
remote: Enumerating objects: 492, done.
remote: Counting objects: 100% (492/492), done.
remote: Compressing objects: 100% (126/126), done.
remote: Total 35951 (delta 381), reused 443 (delta 366), pack-reused 35459
Receiving objects: 100% (35951/35951), 15.70 MiB | 16.09 MiB/s, done.
Resolving deltas: 100% (26243/26243), done.

scottzhu-macbookpro2:workspace scottzhu$ mkdir venv_dir
scottzhu-macbookpro2:workspace scottzhu$ python3 -m venv venv_dir
scottzhu-macbookpro2:workspace scottzhu$ source venv_dir/bin/activate
(venv_dir) scottzhu-macbookpro2:workspace scottzhu$ ls
keras       venv_dir

(venv_dir) scottzhu-macbookpro2:workspace scottzhu$ cd keras

(venv_dir) scottzhu-macbookpro2:workspace scottzhu$ pip install -r requirements.txt
Collecting pandas
  Using cached pandas-1.2.3-cp38-cp38-manylinux1_x86_64.whl (9.7 MB)
Collecting pydot
...
...
...

# Since tf-nightly uses keras-nightly as a dependency, we need to uninstall
# keras-nightly so that tests will run against keras code in local workspace.
(venv_dir) scottzhu-macbookpro2:workspace scottzhu$ pip uninstall keras-nightly
Found existing installation: keras-nightly 2.5.0.dev2021032500
Uninstalling keras-nightly-2.5.0.dev2021032500:
  Successfully uninstalled keras-nightly-2.5.0.dev2021032500

Run tests

We use Bazel to build and run the tests.

Run a test file

For example, to run the tests in keras/engine/base_layer_test.py, we can run the following command at the root directory of the repo.

bazel test keras/engine:base_layer_test

keras/engine is the relative path to the directory containing the BUILD file defing the test. base_layer_test is the test target name defined with tf_py_test in the BUILD file.

Run a single test case

The best way to run a single test case is to comment out the rest of the test cases in a file before runing the test file.

Run all tests

You can run all the tests in a directory locally with the following commmand.

bazel test keras/... --build_tests_only

Useful configs

Here we provide a list of useful configs you can use with Bazel.

bazel test [CONFIGS] [YOUR_TEST]

To use these configs, just replace [CONFIGS] with the actual config in the command above.

  • -c opt enables the optimizations during the build.
  • --test_sharding_strategy=disabled disables the sharding so that all the test outputs are in one file. However, it may slow down the tests for not running in parallel and may cause the test to timeout.