wehub-resource-sync
285 lines
9.9 KiB
Markdown
285 lines
9.9 KiB
Markdown
Keras 3 is a high-velocity open-source project. We welcome contributions!
|
||
|
||
Contributions can be made in a variety of ways, including coding, enriching documentation, refining docstrings, and providing code examples.
|
||
|
||
Please review our
|
||
[AI-Assisted Contribution Policy](#ai-assisted-contribution-policy).
|
||
|
||
## Current items open for contributions
|
||
At [this link](https://github.com/keras-team/keras/issues/18442), you'll find a list of items where your help is needed!
|
||
|
||
|
||
## 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. Unsolicited PRs that attempt to fix complex
|
||
issues without prior discussion in a GitHub issue may be closed.
|
||
|
||
If the changes are minor (simple bug fix or documentation fix), then feel free
|
||
to open a Pull Request (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](https://github.com/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.
|
||
|
||
|
||
|
||
|
||
### Step 5. Code review
|
||
|
||
If the tests fail, look into the error messages and try to fix them.
|
||
|
||
|
||
|
||
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.
|
||
|
||
|
||
|
||
### 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.
|
||
|
||
|
||
|
||
Here is an [example pull request](https://github.com/keras-team/keras/pull/18848)
|
||
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 set up 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](https://github.com/keras-team/keras/tree/master/.devcontainer).
|
||
|
||
### Option 2: Set up a local environment
|
||
|
||
To set up your local dev environment, you will need the following tools.
|
||
|
||
1. [git](https://github.com/) for code repository management.
|
||
2. [python](https://www.python.org/) to build and code in Keras.
|
||
|
||
The following commands check the tools above are successfully installed. Note
|
||
that Keras requires at least Python 3.10 to run.
|
||
|
||
```shell
|
||
git --version
|
||
python --version
|
||
```
|
||
|
||
Clone your forked repo to your local machine. Go to the cloned directory to
|
||
install the dependencies.
|
||
|
||
```shell
|
||
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](https://github.com/keras-team/keras/blob/master/README.md#configuring-your-backend)
|
||
section of the README.
|
||
|
||
You can also add GPU support to your environment, see the
|
||
[Adding GPU support](https://github.com/keras-team/keras/blob/master/README.md#adding-gpu-support)
|
||
section of the README.
|
||
|
||
## Generating public API and formatting the code
|
||
|
||
For the first time you are setting up the repo, please run `pre-commit install`.
|
||
Note that this needs to be done only once at the beginning.
|
||
|
||
Now, whenever you run `git commit -m "<message>"`, three things are
|
||
automatically done:
|
||
|
||
- Public API generation
|
||
- Code formatting
|
||
- Code linting
|
||
|
||
If there's any error, the commit will not go through. Please fix the error (
|
||
most of the times, the error is fixed automatically by the formatter/linter) and
|
||
re-run the following:
|
||
|
||
```
|
||
git add .
|
||
git commit -m "<message>" # This will not get logged as a duplicate commit.
|
||
```
|
||
|
||
In case you want to run the above manually on all files, you can do the
|
||
following:
|
||
|
||
```
|
||
pre-commit run --all-files
|
||
```
|
||
|
||
KerasHub uses [Ruff](https://docs.astral.sh/ruff/) to format the code.
|
||
|
||
### 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)](https://github.com/keras-team/keras/blob/v3.0.0/keras/layers/attention/multi_head_attention.py#L20).
|
||
|
||
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)](https://github.com/keras-team/keras/blob/v3.0.0/keras/utils/text_dataset_utils.py#L27).
|
||
|
||
## Run tests
|
||
|
||
We use [pytest](https://pytest.org/) to run the tests.
|
||
|
||
### Run a test file
|
||
|
||
To run the tests in `keras/src/losses/losses_test.py`, use the following command
|
||
at the root directory of the repo.
|
||
|
||
```shell
|
||
pytest keras/src/losses/losses_test.py
|
||
```
|
||
|
||
### Run a single test case
|
||
|
||
You can specify a single test class to run within a file.
|
||
|
||
```shell
|
||
pytest keras/src/losses/losses_test.py::MeanSquaredErrorTest
|
||
```
|
||
|
||
You can also specify a single test method to run within a class.
|
||
|
||
```shell
|
||
pytest keras/src/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.
|
||
|
||
```shell
|
||
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.
|
||
|
||
```shell
|
||
SKIP_APPLICATIONS_TESTS=True pytest keras
|
||
```
|
||
|
||
To run all tests using a different backend, you can simply specify it on the
|
||
command line.
|
||
|
||
```shell
|
||
KERAS_BACKEND=jax SKIP_APPLICATIONS_TESTS=True pytest keras
|
||
```
|
||
|
||
## AI-Assisted Contribution Policy
|
||
|
||
The Keras project relies on a vibrant, collaborative open-source community. As
|
||
an organization at the forefront of machine learning, we recognize and support
|
||
the use of AI-assisted coding tools to enhance developer productivity.
|
||
|
||
The ultimate responsibility for any code contributed to Keras rests entirely
|
||
with the human author. To maintain the high quality, security, and architectural
|
||
integrity of the Keras codebase, and to respect the time of our maintainers, we
|
||
require all contributors to adhere to the following policy.
|
||
|
||
### 1. Disclosure Requirements
|
||
|
||
If you used an AI coding agent in any capacity in the process of creating the
|
||
pull request, you must disclose this in the PR description. This provides
|
||
necessary context for the reviewers. By opening a pull request which includes AI
|
||
generated code, you accept all responsibility for the code in question and
|
||
guarantee that the content of the pull request complies with the terms of Keras’
|
||
open source license and intellectual property policies.
|
||
|
||
### 2. Acceptable vs. Unacceptable Use
|
||
|
||
#### Acceptable Use:
|
||
|
||
- Using AI tools while writing code you understand.
|
||
- Generating boilerplate code, documentation drafts, or unit test templates that
|
||
you manually review, refine, and test.
|
||
- Using LLMs to help you understand a complex bug or explain a piece of the
|
||
existing Keras codebase locally.
|
||
|
||
#### Unacceptable Use:
|
||
|
||
- **Zero-Review Agent PRs:** Allowing an autonomous AI agent to read an issue,
|
||
generate a patch, and open a Pull Request without comprehensive manual review
|
||
and testing by you.
|
||
- **Blind Copy-Pasting:** Submitting patches generated by an LLM where you do
|
||
not fully grasp the underlying mechanics of the fix.
|
||
- **AI-Generated Code Review Responses:** Using an LLM to automatically generate
|
||
replies to maintainer feedback. Code reviews require human-to-human
|
||
communication. If a maintainer asks an architectural question, you must answer
|
||
it yourself.
|
||
|
||
### 3. Enforcement and PR Closure
|
||
|
||
To keep the project moving efficiently, the Keras maintainer team reserves the
|
||
right to enforce this policy strictly:
|
||
|
||
- **Unaddressed Feedback:** If a maintainer leaves structural or architectural
|
||
feedback and the PR is abandoned, or the responses demonstrate a lack of
|
||
understanding of the submitted code, the PR will be closed.
|
||
- **Policy Violation:** Repeated submission of low-effort, poorly understood
|
||
AI-generated code will result in PR closure and potential restriction from
|
||
contributing to the repository.
|
||
|
||
### Acknowledgment
|
||
|
||
By submitting a Pull Request to Keras, you confirm that you have read this
|
||
policy, understand the code you are submitting, and take full responsibility for
|
||
its accuracy and integration into the codebase.
|