From 79c1bbc8184f4019222e924cedaaeaf150dafe94 Mon Sep 17 00:00:00 2001 From: Luke Wood Date: Sat, 29 Jan 2022 20:19:57 -0800 Subject: [PATCH 1/7] Add a contributing guide --- CONTRIBUTING.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..f3cc09f1dd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,95 @@ +## 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](https://github.com/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](https://i.imgur.com/LHEdIfL.png) + + +### Step 5. Code review + +CI tests will automatically be run directly on your pull request. Their +status will be reported back via GitHub actions. + +There may be +several rounds of comments and code changes before the pull request gets +approved by the reviewer. + +![Approval from reviewer](https://i.imgur.com/zgRziTt.png) + +### 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](https://i.imgur.com/yCEqJsA.png) + +Here is an [example pull request](https://github.com/keras-team/keras/pull/15015) +for your reference. + +## Setup environment + +Setting up your KerasCV development environment is quite easy. You simply +need to run the following commands: + +```shell +git clone https://github.com/YOUR_GITHUB_USERNAME/keras.git +cd keras +pip install ".[tests]" +python setup.py develop +``` + +Following these commands you should be able to run the tests using `pytest keras_cv`. +Please report any issues running tests following these steps. + +## Run tests + +KerasCV is tested using [PyTest](https://docs.pytest.org/en/6.2.x/). + +### Run a test file + +To run a test file, run `pytest path/to/file`. + +### Run a single test case + +To run a single test, you can use `-k=` +to use regular expression to match the test you want to run. For example, you +can use the following command to run all the tests in `cut_mix_test.py`, +whose names contain `label`, + +``` +pytest keras_cv/layers/preprocessing/cut_mix_test.py -k="label" +``` + +### Run all tests + +Running all of the tests in KerasCV is as easy as: +``` +pytest keras_cv/ +``` From 430d634364b1d5bdec4dcadc3fc67b4646f1684c Mon Sep 17 00:00:00 2001 From: Luke Wood Date: Mon, 31 Jan 2022 10:38:22 -0800 Subject: [PATCH 2/7] Address Scott's comments. --- CONTRIBUTING.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f3cc09f1dd..19a46390ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,13 +45,7 @@ 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. - -![Ready to pull](https://i.imgur.com/yCEqJsA.png) - -Here is an [example pull request](https://github.com/keras-team/keras/pull/15015) -for your reference. +Once the pull request is approved, a team member will take care of merging. ## Setup environment @@ -59,8 +53,8 @@ Setting up your KerasCV development environment is quite easy. You simply need to run the following commands: ```shell -git clone https://github.com/YOUR_GITHUB_USERNAME/keras.git -cd keras +git clone https://github.com/YOUR_GITHUB_USERNAME/keras-cv.git +cd keras-cv pip install ".[tests]" python setup.py develop ``` @@ -74,7 +68,7 @@ KerasCV is tested using [PyTest](https://docs.pytest.org/en/6.2.x/). ### Run a test file -To run a test file, run `pytest path/to/file`. +To run a test file, run `pytest path/to/file` from the root directory of keras\_cv. ### Run a single test case @@ -93,3 +87,8 @@ Running all of the tests in KerasCV is as easy as: ``` pytest keras_cv/ ``` + +### Formatting the Code +In order to format the code you can use the `shell/format.sh` script. +If this does not resolve the issue, try updating `isort` and `black` +via `pip install --upgrade black` and `pip install --upgrade isort`. From 037fdde5ef1df93fe81d88688a905a4e930f0f09 Mon Sep 17 00:00:00 2001 From: Luke Wood Date: Mon, 31 Jan 2022 12:08:01 -0800 Subject: [PATCH 3/7] address Matt comments --- CONTRIBUTING.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 19a46390ac..f3b9456274 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,10 @@ 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 your code change involves the fixing of a bug, please include a +[Colab](https://colab.research.google.com/) notebook that shows +how to reproduce the broken behavior. + If the changes are minor (simple bug fix or documentation fix), then feel free to open a PR without discussion. @@ -20,7 +24,7 @@ development environment and run the unit tests. This is covered in section ### 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). +the master branch in [keras-team/keras-cv](https://github.com/keras-team/keras-cv). ### Step 4. Sign the Contributor License Agreement @@ -49,8 +53,10 @@ Once the pull request is approved, a team member will take care of merging. ## Setup environment -Setting up your KerasCV development environment is quite easy. You simply -need to run the following commands: +Setting up your KerasCV development environment requires you to clone the KerasCV repository, +install dependencies, and execute `python setup.py develop`. + +You can achieve this by running the following commands: ```shell git clone https://github.com/YOUR_GITHUB_USERNAME/keras-cv.git @@ -83,7 +89,7 @@ pytest keras_cv/layers/preprocessing/cut_mix_test.py -k="label" ### Run all tests -Running all of the tests in KerasCV is as easy as: +You can run the unit tests for KerasCV by running: ``` pytest keras_cv/ ``` From 99094e59b49c186c5cec99aaf176c40c1bbb9fe3 Mon Sep 17 00:00:00 2001 From: Luke Wood Date: Mon, 31 Jan 2022 13:18:31 -0800 Subject: [PATCH 4/7] update to use github cli --- CONTRIBUTING.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f3b9456274..52c3c77cd2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,18 +53,20 @@ Once the pull request is approved, a team member will take care of merging. ## Setup environment -Setting up your KerasCV development environment requires you to clone the KerasCV repository, -install dependencies, and execute `python setup.py develop`. +Setting up your KerasCV development environment requires you to fork the KerasCV repository, +clone the repository, install dependencies, and execute `python setup.py develop`. You can achieve this by running the following commands: ```shell -git clone https://github.com/YOUR_GITHUB_USERNAME/keras-cv.git +gh repo fork keras-team/keras-cv --clone --remote cd keras-cv pip install ".[tests]" python setup.py develop ``` +The first line relies on having an installation of [the GitHub CLI](https://github.com/cli/cli). + Following these commands you should be able to run the tests using `pytest keras_cv`. Please report any issues running tests following these steps. @@ -95,6 +97,7 @@ pytest keras_cv/ ``` ### Formatting the Code + In order to format the code you can use the `shell/format.sh` script. If this does not resolve the issue, try updating `isort` and `black` via `pip install --upgrade black` and `pip install --upgrade isort`. From 1a9703f2e4c15c62bb33da4d5e90118803a2958b Mon Sep 17 00:00:00 2001 From: Luke Wood Date: Mon, 31 Jan 2022 13:19:01 -0800 Subject: [PATCH 5/7] Update "Format the Code" header --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52c3c77cd2..0b349afb6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,7 @@ You can run the unit tests for KerasCV by running: pytest keras_cv/ ``` -### Formatting the Code +## Formatting the Code In order to format the code you can use the `shell/format.sh` script. If this does not resolve the issue, try updating `isort` and `black` From c83a94e5d2d8518f90c2e747c770fd1d745084b6 Mon Sep 17 00:00:00 2001 From: Luke Wood Date: Mon, 31 Jan 2022 13:28:55 -0800 Subject: [PATCH 6/7] Address introduction of tools comment --- CONTRIBUTING.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b349afb6b..72740319e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,7 +97,17 @@ pytest keras_cv/ ``` ## Formatting the Code +We use `flake8`, `isort` and `black` for code formatting. You can run +the following commands manually every time you want to format your code: + +- Run `shell/format.sh` to format your code +- Run `shell/lint.sh` to check the result. + +If after running these the CI flow is still failing, try updating `flake8`, `isort` and `black`. +This can be done by running `pip install --upgrade black`, `pip install --upgrade flake8`, and +`pip install --upgrade isort`. + +## Community Guidelines + +This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/). -In order to format the code you can use the `shell/format.sh` script. -If this does not resolve the issue, try updating `isort` and `black` -via `pip install --upgrade black` and `pip install --upgrade isort`. From 3347da23db79c32480454fa3607a1defcd4edf49 Mon Sep 17 00:00:00 2001 From: Luke Wood Date: Mon, 31 Jan 2022 21:09:51 -0800 Subject: [PATCH 7/7] Update CONTRIBUTING.md --- CONTRIBUTING.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72740319e0..71bfa15f7e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,12 +28,8 @@ the master branch in [keras-team/keras-cv](https://github.com/keras-team/keras-c ### 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](https://i.imgur.com/LHEdIfL.png) +After creating the pull request, you will need to sign the Google CLA agreement. +The agreement can be foiund at [https://cla.developers.google.com/clas](https://cla.developers.google.com/clas). ### Step 5. Code review