1# Contributing guidelines 2 3## Pull Request Checklist 4 5Before sending your pull requests, make sure you followed this list. 6 7- Read [contributing guidelines](CONTRIBUTING.md). 8- Read [Code of Conduct](CODE_OF_CONDUCT.md). 9- Ensure you have signed the [Contributor License Agreement (CLA)](https://cla.developers.google.com/). 10- Check if my changes are consistent with the [guidelines](https://github.com/tensorflow/tensorflow/blob/master/CONTRIBUTING.md#general-guidelines-and-philosophy-for-contribution). 11- Changes are consistent with the [Coding Style](https://github.com/tensorflow/tensorflow/blob/master/CONTRIBUTING.md#c-coding-style). 12- Run [Unit Tests](https://github.com/tensorflow/tensorflow/blob/master/CONTRIBUTING.md#running-unit-tests). 13 14## How to become a contributor and submit your own code 15 16### Contributor License Agreements 17 18We'd love to accept your patches! Before we can take them, we have to jump a couple of legal hurdles. 19 20Please fill out either the individual or corporate Contributor License Agreement (CLA). 21 22 * If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an [individual CLA](https://code.google.com/legal/individual-cla-v1.0.html). 23 * If you work for a company that wants to allow you to contribute your work, then you'll need to sign a [corporate CLA](https://code.google.com/legal/corporate-cla-v1.0.html). 24 25Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to accept your pull requests. 26 27***NOTE***: Only original source code from you and other people that have signed the CLA can be accepted into the main repository. 28 29### Contributing code 30 31If you have improvements to TensorFlow, send us your pull requests! For those 32just getting started, Github has a 33[how to](https://help.github.com/articles/using-pull-requests/). 34 35TensorFlow team members will be assigned to review your pull requests. Once the 36pull requests are approved and pass continuous integration checks, a TensorFlow 37team member will apply `ready to pull` label to your change. This means we are 38working on getting your pull request submitted to our internal repository. After 39the change has been submitted internally, your pull request will be merged 40automatically on GitHub. 41 42If you want to contribute, start working through the TensorFlow codebase, 43navigate to the 44[Github "issues" tab](https://github.com/tensorflow/tensorflow/issues) and start 45looking through interesting issues. If you are not sure of where to start, then 46start by trying one of the smaller/easier issues here i.e. 47[issues with the "good first issue" label](https://github.com/tensorflow/tensorflow/labels/good%20first%20issue) 48and then take a look at the 49[issues with the "contributions welcome" label](https://github.com/tensorflow/tensorflow/labels/stat%3Acontributions%20welcome). 50These are issues that we believe are particularly well suited for outside 51contributions, often because we probably won't get to them right now. If you 52decide to start on an issue, leave a comment so that other people know that 53you're working on it. If you want to help out, but not alone, use the issue 54comment thread to coordinate. 55 56### Contribution guidelines and standards 57 58Before sending your pull request for 59[review](https://github.com/tensorflow/tensorflow/pulls), 60make sure your changes are consistent with the guidelines and follow the 61TensorFlow coding style. 62 63#### General guidelines and philosophy for contribution 64 65* Include unit tests when you contribute new features, as they help to a) 66 prove that your code works correctly, and b) guard against future breaking 67 changes to lower the maintenance cost. 68* Bug fixes also generally require unit tests, because the presence of bugs 69 usually indicates insufficient test coverage. 70* Keep API compatibility in mind when you change code in core TensorFlow, 71 e.g., code in 72 [tensorflow/core](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/core) 73 and 74 [tensorflow/python](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/python). 75 TensorFlow has passed version 1.0 and hence cannot make 76 non-backward-compatible API changes without a major release. Reviewers of 77 your pull request will comment on any API compatibility issues. 78* When you contribute a new feature to TensorFlow, the maintenance burden is 79 (by default) transferred to the TensorFlow team. This means that the benefit 80 of the contribution must be compared against the cost of maintaining the 81 feature. 82* Full new features (e.g., a new op implementing a cutting-edge algorithm) 83 typically will live in 84 [tensorflow/addons](https://github.com/tensorflow/addons) to get some 85 airtime before a decision is made regarding whether they are to be migrated 86 to the core. 87* As every PR requires several CPU/GPU hours of CI testing, we discourage 88 submitting PRs to fix one typo, one warning,etc. We recommend fixing the 89 same issue at the file level at least (e.g.: fix all typos in a file, fix 90 all compiler warning in a file, etc.) 91 92#### License 93 94Include a license at the top of new files. 95 96* [C/C++ license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/op.cc#L1) 97* [Python license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/ops/nn.py#L1) 98* [Java license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/java/src/main/java/org/tensorflow/Graph.java#L1) 99* [Go license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/go/operation.go#L1) 100* [Bash license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/ci_build/ci_sanity.sh#L2) 101* [HTML license example](https://github.com/tensorflow/tensorboard/blob/master/tensorboard/components/tf_backend/tf-backend.html#L2) 102* [JavaScript/TypeScript license example](https://github.com/tensorflow/tensorboard/blob/master/tensorboard/components/tf_backend/backend.ts#L1) 103 104Bazel BUILD files also need to include a license section, e.g., 105[BUILD example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/BUILD#L61). 106 107#### C++ coding style 108 109Changes to TensorFlow C++ code should conform to 110[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). 111 112Use `clang-tidy` to check your C/C++ changes. To install `clang-tidy` on ubuntu:16.04, do: 113 114```bash 115apt-get install -y clang-tidy 116``` 117 118You can check a C/C++ file by doing: 119 120 121```bash 122clang-format <my_cc_file> --style=google > /tmp/my_cc_file.cc 123diff <my_cc_file> /tmp/my_cc_file.cc 124``` 125 126#### Python coding style 127 128Changes to TensorFlow Python code should conform to 129[Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md) 130 131Use `pylint` to check your Python changes. To install `pylint` and check a file 132with `pylint` against TensorFlow's custom style definition: 133 134```bash 135pip install pylint 136pylint --rcfile=tensorflow/tools/ci_build/pylintrc myfile.py 137``` 138 139Note `pylint --rcfile=tensorflow/tools/ci_build/pylintrc` should run from the 140top level tensorflow directory. 141 142#### Coding style for other languages 143 144* [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) 145* [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) 146* [Google Shell Style Guide](https://google.github.io/styleguide/shell.xml) 147* [Google Objective-C Style Guide](https://google.github.io/styleguide/objcguide.html) 148 149#### Running sanity check 150 151If you have Docker installed on your system, you can perform a sanity check on 152your changes by running the command: 153 154```bash 155tensorflow/tools/ci_build/ci_build.sh CPU tensorflow/tools/ci_build/ci_sanity.sh 156``` 157 158This will catch most license, Python coding style and BUILD file issues that 159may exist in your changes. 160 161#### Running unit tests 162 163There are two ways to run TensorFlow unit tests. 164 1651. Using tools and libraries installed directly on your system. 166 167 Refer to the 168 [CPU-only developer Dockerfile](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/dockerfiles/dockerfiles/devel-cpu.Dockerfile) 169 and 170 [GPU developer Dockerfile](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/dockerfiles/dockerfiles/devel-gpu.Dockerfile) 171 for the required packages. Alternatively, use the said 172 [Docker images](https://hub.docker.com/r/tensorflow/tensorflow/tags/), e.g., 173 `tensorflow/tensorflow:devel` and `tensorflow/tensorflow:devel-gpu` for 174 development to avoid installing the packages directly on your system (in 175 which case remember to change directory from `/root` to `/tensorflow` once 176 you get into the running container so `bazel` can find the `tensorflow` 177 workspace). 178 179 Once you have the packages installed, you can run a specific unit test in 180 bazel by doing as follows: 181 182 If the tests are to be run on GPU, add CUDA paths to LD_LIBRARY_PATH and add 183 the `cuda` option flag 184 185 ```bash 186 export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/cuda/lib64:/usr/local/cuda/extras/CUPTI/lib64:$LD_LIBRARY_PATH" 187 188 export flags="--config=opt --config=cuda -k" 189 ``` 190 191 For example, to run all tests under tensorflow/python, do: 192 193 ```bash 194 bazel test ${flags} //tensorflow/python/... 195 ``` 196 1972. Using [Docker](https://www.docker.com) and TensorFlow's CI scripts. 198 199 ```bash 200 # Install Docker first, then this will build and run cpu tests 201 tensorflow/tools/ci_build/ci_build.sh CPU bazel test //tensorflow/... 202 ``` 203 204 See 205 [TensorFlow Builds](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/tools/ci_build) 206 for details. 207