Some additions to the CONTRIBUTING guide (#1685)

* Some additions to the CONTRIBUTING guide

- how to run black if so desired
- install instructions for devs (following GH action)
- running tests
- minor fixups

If there is a guide on how to best add new models, it would be a good
idea to link it here, since I imagine this is what many contributors
would need most help with.

* [skip ci] empty commit to skip ci
main
Benjamin Bossan 1 year ago committed by GitHub
parent a32c4eff69
commit c9406ce608
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -4,9 +4,9 @@ Contriubtions to `timm` for code, documentation, tests are more than welcome!
There haven't been any formal guidelines to date so please bear with me, and feel free to add to this guide. There haven't been any formal guidelines to date so please bear with me, and feel free to add to this guide.
# Code # Coding style
Code linting and auto-format (black) are not currently in place but open to consideration. In the meantime, the style to follow is (mostly) aligned with Google's guide: https://google.github.io/styleguide/pyguide.html Code linting and auto-format (black) are not currently in place but open to consideration. In the meantime, the style to follow is (mostly) aligned with Google's guide: https://google.github.io/styleguide/pyguide.html.
A few specific differences from Google style (or black) A few specific differences from Google style (or black)
1. Line length is 120 char. Going over is okay in some cases (e.g. I prefer not to break URL across lines). 1. Line length is 120 char. Going over is okay in some cases (e.g. I prefer not to break URL across lines).
@ -51,8 +51,15 @@ This is YES:
When there is descrepancy in a given source file (there are many origins for various bits of code and not all have been updated to what I consider current goal), please follow the style in a given file. When there is descrepancy in a given source file (there are many origins for various bits of code and not all have been updated to what I consider current goal), please follow the style in a given file.
PR with pure formatting / style fixes will be accepted but only in isolation from functional changes, best to ask before starting such a change. In general, if you add new code, formatting it with black using the following options should result in a style that is compatible with the rest of the code base:
```
black --skip-string-normalization --line-length 120 <path-to-file>
```
Avoid formatting code that is unrelated to your PR though.
PR with pure formatting / style fixes will be accepted but only in isolation from functional changes, best to ask before starting such a change.
# Documentation # Documentation
@ -64,8 +71,42 @@ When type annotations are used for a function, as per the Google pyguide, they s
There are a LOT of gaps in current documentation relative to the functionality in timm, please, document away! There are a LOT of gaps in current documentation relative to the functionality in timm, please, document away!
# Questions # Installation
If you have any questions about contribution, where / how to contribute, please ask in the Discussions (there is a `Contributing` topic). Create a Python virtual environment using Python 3.10. Inside the environment, install the following test dependencies:
```
python -m pip install pytest pytest-timeout pytest-xdist pytest-forked expecttest
```
Install `torch` and `torchvision` using the instructions matching your system as listed on the [PyTorch website](https://pytorch.org/).
Then install the remaining dependencies:
```
python -m pip install -r requirements.txt
python -m pip install --no-cache-dir git+https://github.com/mapillary/inplace_abn.git
python -m pip install -e .
```
## Unit tests
Run the tests using:
```
pytest tests/
```
Since the whole test suite takes a lot of time to run locally (a few hours), you may want to select a subset of tests relating to the changes you made by using the `-k` option of [`pytest`](https://docs.pytest.org/en/7.1.x/example/markers.html#using-k-expr-to-select-tests-based-on-their-name). Moreover, running tests in parallel (in this example 4 processes) with the `-n` option may help:
```
pytest -k "substring-to-match" -n 4 tests/
```
## Building documentation
Please refer to [this document](https://github.com/huggingface/pytorch-image-models/tree/main/hfdocs).
# Questions
If you have any questions about contribution, where / how to contribute, please ask in the [Discussions](https://github.com/huggingface/pytorch-image-models/discussions/categories/contributing) (there is a `Contributing` topic).

Loading…
Cancel
Save