Skip to content

Commit 1eea133

Browse files
authored
Add a contributing guide (#67)
* Add a contributing guide * Address Scott's comments. * address Matt comments * update to use github cli * Update "Format the Code" header * Address introduction of tools comment * Update CONTRIBUTING.md
1 parent e301360 commit 1eea133

File tree

1 file changed

+109
-0
lines changed

1 file changed

+109
-0
lines changed

CONTRIBUTING.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
## How to contribute code
2+
3+
Follow these steps to submit your code contribution.
4+
5+
### Step 1. Open an issue
6+
7+
Before making any changes, we recommend opening an issue (if one doesn't already
8+
exist) and discussing your proposed changes. This way, we can give you feedback
9+
and validate the proposed changes.
10+
11+
If your code change involves the fixing of a bug, please include a
12+
[Colab](https://colab.research.google.com/) notebook that shows
13+
how to reproduce the broken behavior.
14+
15+
If the changes are minor (simple bug fix or documentation fix), then feel free
16+
to open a PR without discussion.
17+
18+
### Step 2. Make code changes
19+
20+
To make code changes, you need to fork the repository. You will need to setup a
21+
development environment and run the unit tests. This is covered in section
22+
"Setup environment".
23+
24+
### Step 3. Create a pull request
25+
26+
Once the change is ready, open a pull request from your branch in your fork to
27+
the master branch in [keras-team/keras-cv](https://github.com/keras-team/keras-cv).
28+
29+
### Step 4. Sign the Contributor License Agreement
30+
31+
After creating the pull request, you will need to sign the Google CLA agreement.
32+
The agreement can be foiund at [https://cla.developers.google.com/clas](https://cla.developers.google.com/clas).
33+
34+
35+
### Step 5. Code review
36+
37+
CI tests will automatically be run directly on your pull request. Their
38+
status will be reported back via GitHub actions.
39+
40+
There may be
41+
several rounds of comments and code changes before the pull request gets
42+
approved by the reviewer.
43+
44+
![Approval from reviewer](https://i.imgur.com/zgRziTt.png)
45+
46+
### Step 6. Merging
47+
48+
Once the pull request is approved, a team member will take care of merging.
49+
50+
## Setup environment
51+
52+
Setting up your KerasCV development environment requires you to fork the KerasCV repository,
53+
clone the repository, install dependencies, and execute `python setup.py develop`.
54+
55+
You can achieve this by running the following commands:
56+
57+
```shell
58+
gh repo fork keras-team/keras-cv --clone --remote
59+
cd keras-cv
60+
pip install ".[tests]"
61+
python setup.py develop
62+
```
63+
64+
The first line relies on having an installation of [the GitHub CLI](https://github.com/cli/cli).
65+
66+
Following these commands you should be able to run the tests using `pytest keras_cv`.
67+
Please report any issues running tests following these steps.
68+
69+
## Run tests
70+
71+
KerasCV is tested using [PyTest](https://docs.pytest.org/en/6.2.x/).
72+
73+
### Run a test file
74+
75+
To run a test file, run `pytest path/to/file` from the root directory of keras\_cv.
76+
77+
### Run a single test case
78+
79+
To run a single test, you can use `-k=<your_regex>`
80+
to use regular expression to match the test you want to run. For example, you
81+
can use the following command to run all the tests in `cut_mix_test.py`,
82+
whose names contain `label`,
83+
84+
```
85+
pytest keras_cv/layers/preprocessing/cut_mix_test.py -k="label"
86+
```
87+
88+
### Run all tests
89+
90+
You can run the unit tests for KerasCV by running:
91+
```
92+
pytest keras_cv/
93+
```
94+
95+
## Formatting the Code
96+
We use `flake8`, `isort` and `black` for code formatting. You can run
97+
the following commands manually every time you want to format your code:
98+
99+
- Run `shell/format.sh` to format your code
100+
- Run `shell/lint.sh` to check the result.
101+
102+
If after running these the CI flow is still failing, try updating `flake8`, `isort` and `black`.
103+
This can be done by running `pip install --upgrade black`, `pip install --upgrade flake8`, and
104+
`pip install --upgrade isort`.
105+
106+
## Community Guidelines
107+
108+
This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
109+

0 commit comments

Comments
 (0)