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 [howto](https://help.github.com/articles/using-pull-requests/).
33
34TensorFlow team members will be assigned to review your pull requests. Once the
35pull requests are approved and pass continuous integration checks, a TensorFlow
36team member will apply `ready to pull` label to your change. This means we are
37working on getting your pull request submitted to our internal repository. After
38the change has been submitted internally, your pull request will be merged
39automatically on GitHub.
40
41If you want to contribute but you're not sure where to start, take a look at the
42[issues with the "contributions welcome" label](https://github.com/tensorflow/tensorflow/labels/stat%3Acontributions%20welcome).
43These are issues that we believe are particularly well suited for outside
44contributions, often because we probably won't get to them right now. If you
45decide to start on an issue, leave a comment so that other people know that
46you're working on it. If you want to help out, but not alone, use the issue
47comment thread to coordinate.
48
49### Contribution guidelines and standards
50
51Before sending your pull request for
52[review](https://github.com/tensorflow/tensorflow/pulls),
53make sure your changes are consistent with the guidelines and follow the
54TensorFlow coding style.
55
56#### General guidelines and philosophy for contribution
57
58*   Include unit tests when you contribute new features, as they help to a)
59    prove that your code works correctly, and b) guard against future breaking
60    changes to lower the maintenance cost.
61*   Bug fixes also generally require unit tests, because the presence of bugs
62    usually indicates insufficient test coverage.
63*   Keep API compatibility in mind when you change code in core TensorFlow,
64    e.g., code in
65    [tensorflow/core](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/core)
66    and
67    [tensorflow/python](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/python).
68    TensorFlow has reached version 1 and hence cannot make
69    non-backward-compatible API changes without a major release. Reviewers of
70    your pull request will comment on any API compatibility issues.
71*   When you contribute a new feature to TensorFlow, the maintenance burden is
72    (by default) transferred to the TensorFlow team. This means that benefit of
73    the contribution must be compared against the cost of maintaining the
74    feature.
75*   Full new features (e.g., a new op implementing a cutting-edge algorithm)
76    typically will live in
77    [tensorflow/addons](https://github.com/tensorflow/addons) to get some
78    airtime before decision is made regarding whether they are to be migrated to
79    the core.
80
81#### License
82
83Include a license at the top of new files.
84
85* [C/C++ license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/op.cc#L1)
86* [Python license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/ops/nn.py#L1)
87* [Java license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/java/src/main/java/org/tensorflow/Graph.java#L1)
88* [Go license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/go/operation.go#L1)
89* [Bash license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/ci_build/ci_sanity.sh#L2)
90* [HTML license example](https://github.com/tensorflow/tensorboard/blob/master/tensorboard/components/tf_backend/tf-backend.html#L2)
91* [JavaScript/TypeScript license example](https://github.com/tensorflow/tensorboard/blob/master/tensorboard/components/tf_backend/backend.ts#L1)
92
93Bazel BUILD files also need to include a license section, e.g.,
94[BUILD example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/BUILD#L61).
95
96#### C++ coding style
97
98Changes to TensorFlow C++ code should conform to
99[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
100
101Use `clang-tidy` to check your C/C++ changes. To install `clang-tidy` on ubuntu:16.04, do:
102
103```bash
104apt-get install -y clang-tidy
105```
106
107You can check a C/C++ file by doing:
108
109
110```bash
111clang-format <my_cc_file> --style=google > /tmp/my_cc_file.cc
112diff <my_cc_file> /tmp/my_cc_file.cc
113```
114
115#### Python coding style
116
117Changes to TensorFlow Python code should conform to
118[Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md)
119
120Use `pylint` to check your Python changes. To install `pylint` and
121retrieve TensorFlow's custom style definition:
122
123```bash
124pip install pylint
125wget -O /tmp/pylintrc https://raw.githubusercontent.com/tensorflow/tensorflow/master/tensorflow/tools/ci_build/pylintrc
126```
127
128To check a file with `pylint`:
129
130```bash
131pylint --rcfile=/tmp/pylintrc myfile.py
132```
133
134#### Coding style for other languages
135
136* [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)
137* [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
138* [Google Shell Style Guide](https://google.github.io/styleguide/shell.xml)
139* [Google Objective-C Style Guide](https://google.github.io/styleguide/objcguide.html)
140
141#### Running sanity check
142
143If you have Docker installed on your system, you can perform a sanity check on
144your changes by running the command:
145
146```bash
147tensorflow/tools/ci_build/ci_build.sh CPU tensorflow/tools/ci_build/ci_sanity.sh
148```
149
150This will catch most license, Python coding style and BUILD file issues that
151may exist in your changes.
152
153#### Running unit tests
154
155There are two ways to run TensorFlow unit tests.
156
1571.  Using tools and libraries installed directly on your system.
158
159    Refer to the
160    [CPU-only developer Dockerfile](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/docker/Dockerfile.devel)
161    and
162    [GPU developer Dockerfile](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/docker/Dockerfile.devel-gpu)
163    for the required packages. Alternatively, use the said
164    [Docker images](https://hub.docker.com/r/tensorflow/tensorflow/tags/), e.g.,
165    `tensorflow/tensorflow:nightly-devel` and
166    `tensorflow/tensorflow:nightly-devel-gpu` for development to avoid
167    installing the packages directly on your system (in which case remember to
168    change directory from `/root` to `/tensorflow` once you get into the running
169    container so `bazel` can find the `tensorflow` workspace).
170
171    Once you have the packages installed, you can run a specific unit test in
172    bazel by doing as follows:
173
174    If the tests are to be run on GPU, add CUDA paths to LD_LIBRARY_PATH and add
175    the `cuda` option flag
176
177    ```bash
178    export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/cuda/lib64:/usr/local/cuda/extras/CUPTI/lib64:$LD_LIBRARY_PATH"
179
180    export flags="--config=opt --config=cuda -k"
181    ```
182
183    For example, to run all tests under tensorflow/python, do:
184
185    ```bash
186    bazel test ${flags} //tensorflow/python/...
187    ```
188
1892.  Using [Docker](https://www.docker.com) and TensorFlow's CI scripts.
190
191    ```bash
192    # Install Docker first, then this will build and run cpu tests
193    tensorflow/tools/ci_build/ci_build.sh CPU bazel test //tensorflow/...
194    ```
195
196    See
197    [TensorFlow Builds](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/tools/ci_build)
198    for details.
199