|
| 1 | +# Contributing to Torchvision |
| 2 | + |
| 3 | +We want to make contributing to this project as easy and transparent as possible. |
| 4 | + |
| 5 | +## TL;DR |
| 6 | + |
| 7 | +We appreciate all contributions. If you are interested in contributing to Torchvision, there are many ways to help out. |
| 8 | +Your contributions may fall into the following categories: |
| 9 | + |
| 10 | +- It helps the project if you could |
| 11 | + - Report issues you're facing |
| 12 | + - Give a :+1: on issues that others reported and that are relevant to you |
| 13 | + |
| 14 | +- Answering queries on the issue tracker, investigating bugs are very valuable contributions to the project. |
| 15 | + |
| 16 | +- You would like to improve the documentation. This is no less important than improving the library itself! |
| 17 | +If you find a typo in the documentation, do not hesitate to submit a GitHub pull request. |
| 18 | + |
| 19 | +- If you would like to fix a bug |
| 20 | + - please pick one from the [list of open issues labelled as "help wanted"](https://github.com/pytorch/vision/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) |
| 21 | + - comment on the issue that you want to work on this issue |
| 22 | + - send a PR with your fix, see below. |
| 23 | + |
| 24 | +- If you plan to contribute new features, utility functions or extensions, please first open an issue and discuss the feature with us. |
| 25 | + |
| 26 | +## Issues |
| 27 | + |
| 28 | +We use GitHub issues to track public bugs. Please ensure your description is |
| 29 | +clear and has sufficient instructions to be able to reproduce the issue. |
| 30 | + |
| 31 | +## Development installation |
| 32 | + |
| 33 | +### Install PyTorch Nightly |
| 34 | + |
| 35 | +```bash |
| 36 | +conda install pytorch -c pytorch-nightly |
| 37 | +# or with pip (see https://pytorch.org/get-started/locally/) |
| 38 | +# pip install numpy |
| 39 | +# pip install --pre torch -f https://download.pytorch.org/whl/nightly/cu102/torch_nightly.html |
| 40 | +``` |
| 41 | + |
| 42 | +### Install Torchvision |
| 43 | + |
| 44 | +```bash |
| 45 | +git clone https://github.com/pytorch/vision.git |
| 46 | +cd vision |
| 47 | +python setup.py install |
| 48 | +# or, for OSX |
| 49 | +# MACOSX_DEPLOYMENT_TARGET=10.9 CC=clang CXX=clang++ python setup.py install |
| 50 | +# for C++ debugging, please use DEBUG=1 |
| 51 | +# DEBUG=1 python setup.py install |
| 52 | +pip install flake8 typing mypy pytest scipy |
| 53 | +``` |
| 54 | +You may also have to install `libpng-dev` and `libjpeg-turbo8-dev` libraries: |
| 55 | +```bash |
| 56 | +conda install libpng jpeg |
| 57 | +``` |
| 58 | + |
| 59 | +## Development Process |
| 60 | + |
| 61 | +If you plan to modify the code or documentation, please follow the steps below: |
| 62 | + |
| 63 | +1. Fork the repository and create your branch from `master`. |
| 64 | +2. If you have modified the code (new feature or bug-fix), please add unit tests. |
| 65 | +3. If you have changed APIs, update the documentation. Make sure the documentation builds. |
| 66 | +4. Ensure the test suite passes. |
| 67 | +5. Make sure your code passes `flake8` formatting check. |
| 68 | + |
| 69 | +For more details about pull requests, |
| 70 | +please read [GitHub's guides](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). |
| 71 | + |
| 72 | +If you would like to contribute a new model, please see [here](#New-model). |
| 73 | + |
| 74 | +If you would like to contribute a new dataset, please see [here](#New-dataset). |
| 75 | + |
| 76 | +### Code formatting and typing |
| 77 | + |
| 78 | +New code should be compatible with Python 3.X versions and be compliant with PEP8. To check the codebase, please run |
| 79 | +```bash |
| 80 | +flake8 --config=setup.cfg . |
| 81 | +``` |
| 82 | + |
| 83 | +The codebase has type annotations, please make sure to add type hints if required. We use `mypy` tool for type checking: |
| 84 | +```bash |
| 85 | +mypy --config-file mypy.ini |
| 86 | +``` |
| 87 | + |
| 88 | +### Unit tests |
| 89 | + |
| 90 | +If you have modified the code by adding a new feature or a bug-fix, please add unit tests for that. To run a specific |
| 91 | +test: |
| 92 | +```bash |
| 93 | +pytest test/<test-module.py> -vvv -k <test_myfunc> |
| 94 | +# e.g. pytest test/test_transforms.py -vvv -k test_crop |
| 95 | +``` |
| 96 | + |
| 97 | +If you would like to run all tests: |
| 98 | +```bash |
| 99 | +pytest test -vvv |
| 100 | +``` |
| 101 | + |
| 102 | +### Documentation |
| 103 | + |
| 104 | +Torchvision uses [Google style](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) |
| 105 | +for formatting docstrings. Length of line inside docstrings block must be limited to 120 characters. |
| 106 | + |
| 107 | +Please, follow the instructions to build and deploy the documentation locally. |
| 108 | + |
| 109 | +#### Install requirements |
| 110 | + |
| 111 | +```bash |
| 112 | +cd docs |
| 113 | +pip install -r requirements.txt |
| 114 | +``` |
| 115 | + |
| 116 | +#### Build |
| 117 | + |
| 118 | +```bash |
| 119 | +cd docs |
| 120 | +make html |
| 121 | +``` |
| 122 | + |
| 123 | +#### Local deployment |
| 124 | + |
| 125 | +Please, use python 3.X for the command below: |
| 126 | +```bash |
| 127 | +cd docs/build/html |
| 128 | +python -m http.server <port> |
| 129 | +# e.g. python -m http.server 1234 |
| 130 | +``` |
| 131 | +Then open the browser at `0.0.0.0:<port>` (e.g. `0.0.0.0:1234`) |
| 132 | + |
| 133 | +### New model |
| 134 | + |
| 135 | +More details on how to add a new model will be provided later. Please, do not send any PR with a new model without discussing |
| 136 | +it in an issue as, most likely, it will not be accepted. |
| 137 | + |
| 138 | +### New dataset |
| 139 | + |
| 140 | +More details on how to add a new dataset will be provided later. Please, do not send any PR with a new dataset without discussing |
| 141 | +it in an issue as, most likely, it will not be accepted. |
| 142 | + |
| 143 | +### Pull Request |
| 144 | + |
| 145 | +If all previous checks (flake8, mypy, unit tests) are passing, please send a PR. Submitted PR will pass other tests on |
| 146 | +different operation systems, python versions and hardwares. |
| 147 | + |
| 148 | +For more details about pull requests workflow, |
| 149 | +please read [GitHub's guides](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). |
| 150 | + |
| 151 | +## License |
| 152 | + |
| 153 | +By contributing to Torchvision, you agree that your contributions will be licensed |
| 154 | +under the LICENSE file in the root directory of this source tree. |
0 commit comments