Skip to content
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
49 changes: 39 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,21 +75,50 @@ If you would like to contribute a new dataset, please see [here](#New-dataset).

### Code formatting and typing

Contributions should be compatible with Python 3.X versions and be compliant with PEP8. To check the codebase, please
either run
#### Formatting

The torchvision code is formatted by [black](https://black.readthedocs.io/en/stable/),
and checked against pep8 compliance with [flake8](https://flake8.pycqa.org/en/latest/).
Instead of relying directly on `black` however, we rely on
[ufmt](https://github.com/omnilib/ufmt), for compatibility reasons with Facebook
internal infrastructure.

To format your code, install `ufmt` with `pip install ufmt` and use e.g.:

```bash
pre-commit run --all-files
ufmt format torchvision
```
or run

For the vast majority of cases, this is all you should need to run. For the
formatting to be a bit faster, you can also choose to only apply `ufmt` to the
files that were edited in your PR with e.g.:

```bash
pre-commit install
```
once to perform these checks automatically before every `git commit`. If `pre-commit` is not available you can install
it with
```
pip install pre-commit
ufmt format `git diff main --name-only`
```

Similarly, you can check for `flake8` errors with `flake8 torchvision`, although
they should be fairly rare considering that most of the errors are automatically
taken care of by `ufmt` already.

##### Pre-commit hooks

For convenience and **purely optionally**, you can rely on [pre-commit
hooks](https://pre-commit.com/) which will run both `ufmt` and `flake8` prior to
every commit.

First install the `pre-commit` package with `pip install pre-commit`, and then
run `pre-commit install` at the root of the repo for the hooks to be set up -
that's it.

Feel free to read the [pre-commit docs](https://pre-commit.com/#usage) to learn
more and improve your workflow. You'll see for example that `pre-commit run
--all-files` will run both `ufmt` and `flake8` without the need for you to
commit anything, and that the `--no-verify` flag can be added to `git commit` to
temporarily deactivate the hooks.
Comment on lines +114 to +118
Copy link
Collaborator

Choose a reason for hiding this comment

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

I would think that someone who wants to know more about the tools they are using to do that without extra instructions. Given that we only describe how to format / check the code here, I think this can be safely removed. No strong opinion.

Copy link
Member Author

Choose a reason for hiding this comment

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

For this part, I mostly wanted to mention the pre-commit run --all-files command and the --no-verify flag, which I think are important to know for regular development.
Then it becomes a matter of linking to the docs or not, I feel like there's no harm in encouraging contributors to check them?


#### Type annotations

The codebase has type annotations, please make sure to add type hints if required. We use `mypy` tool for type checking:
```bash
mypy --config-file mypy.ini
Expand Down