keras-team--keras
wehub-resource-sync
285 行
9.9 KiB
Markdown
285 行
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.
|