Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a contributing guide #67

Merged
merged 7 commits into from
Feb 1, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
## How to contribute code
LukeWood marked this conversation as resolved.
Show resolved Hide resolved

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 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.

### Step 2. Make code changes

To make code changes, you need to fork the repository. You will need to setup a
LukeWood marked this conversation as resolved.
Show resolved Hide resolved
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-cv](https://github.com/keras-team/keras-cv).

### Step 4. Sign the Contributor License Agreement

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

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 team member will take care of merging.

## Setup environment

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
gh repo fork keras-team/keras-cv --clone --remote
cd keras-cv
pip install ".[tests]"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is ".[test]"? Usually we list all the required dependency in a requirements.txt file, and use pip install -r requirements.txt.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.[tests] installs everything required to run unit tests. You can see how this is handled in KerasTuner as well:
https://github.com/keras-team/keras-tuner/blob/master/setup.py#L40

So, installing:

pip install .

will install the list on line 30. pip install .[tests] will also install pytest, flake8, isort, etc.

WDYT?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally am a fan of the setup.py dependency management system.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure! I don't really know enough about what is common practice in the python packaging world (or is this a legitimate source of contention?). It is nice to be able to split the testing and package requirements.

Some discussion:
https://stackoverflow.com/q/43658870
https://packaging.python.org/en/latest/discussions/install-requires-vs-requirements/

install_requires works and we have it now, so I am fine to leave as is unless we have a good reason to switch.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some extra context: the benefit of requirements is you can pin versions.

But at Google we are forced to update all dependencies anyways, so for Keras I think install_requires is superior.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If requirements.txt makes it easier to pin a system installed tensorflow that might be a reason to use it. I am not sure, but for running cloud TPU jobs with the setup.py we have today, I've needed to hack it up to stop it from installing a new tf version that does not have proper TPU support. No need to resolve here, but that's something I will keep looking into.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest using setup.py. One caveat is that the current setting for version number [Link] may throw an error when installing with pip install . because it imports the package to get the version number before installing anything, which may encounter some not installed packages. For example, the user would have to install tensorflow before running pip install .. It is not a big deal though. The user can tell which package to install from the error.

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.

## 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` from the root directory of keras\_cv.

### Run a single test case

To run a single test, you can use `-k=<your_regex>`
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

You can run the unit tests for KerasCV by running:
```
pytest keras_cv/
```
LukeWood marked this conversation as resolved.
Show resolved Hide resolved

## Formatting the Code
LukeWood marked this conversation as resolved.
Show resolved Hide resolved
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/).