|
1 | | -# Contributing guidelines |
2 | | - |
3 | | -## Pull Request Checklist |
4 | | - |
5 | | -Before 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 |
| 1 | +# Contribution rules |
15 | 2 |
|
16 | | -### Contributor License Agreements |
| 3 | +- NVIDIA TensorFlow Coding Style Guide can be found [here](STYLE_GUIDE.md). We follow [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with few exceptions and additional guidelines regarding NVIDIA TensorFlow-specific cases. See the NVIDIA TensorFlow Coding Style Guide for details. When no rules can be found, follow the already occuring conventions. If there is no precedence in our codebase we are open to discussion. Ensure that your contribution passes the `make lint` check. It applies rules to the following: |
| 4 | + - class, function/method, and variable/field naming |
| 5 | + - comment style |
| 6 | + - indentation |
| 7 | + - line length |
| 8 | +- Avoid introducing unnecessary complexity into existing code so that maintainability and readability are preserved. |
| 9 | +- Try to keep pull requests (PRs) as concise as possible: |
| 10 | + - Avoid committing commented-out code. |
| 11 | + - Wherever possible, each PR should address a single concern. If there are several otherwise-unrelated things that should be fixed to reach a desired endpoint, it is perfectly fine to open several PRs and state in the description which PR depends on another PR. The more complex the changes are in a single PR, the more time it will take to review those changes. |
| 12 | +- Write PR and commit titles using imperative mood. |
| 13 | + - Format commit messages sticking to rules described in [this](https://chris.beams.io/posts/git-commit/) guide. |
| 14 | +- Make sure that the build log is clean, meaning no warnings or errors should be present. |
| 15 | +- To add or disable functionality: |
| 16 | + - Add a CMake option with a default value that matches the existing behavior. |
| 17 | + - Where entire files can be included/excluded based on the value of this option, selectively include/exclude the relevant files from compilation by modifying `CMakeLists.txt` rather than using `#if` guards around the entire body of each file. |
| 18 | + - Where the functionality involves minor changes to existing files, use `#if` guards. |
| 19 | +- NVIDIA TensorFlow's default build assumes recent versions of NVIDIA TensorFlow's dependencies (CUDA, cuDNN, TensorRT, etc.). Contributions that add compatibility with older versions of those dependencies will be considered, but NVIDIA cannot guarantee that all possible build configurations work, are not broken by future contributions, and retain highest performance. |
| 20 | +- Make sure that you can contribute your work to open source (no license and/or patent conflict is introduced by your code). You need to [`sign`](#Sign) your commit. |
| 21 | +- Thanks in advance for your patience as we review your contributions; we do appreciate them! |
17 | 22 |
|
18 | | -We'd love to accept your patches! Before we can take them, we have to jump a couple of legal hurdles. |
| 23 | +<a name="Sign"></a>Sign your Work |
| 24 | +-------------- |
19 | 25 |
|
20 | | -Please fill out either the individual or corporate Contributor License Agreement (CLA). |
| 26 | +We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license. |
21 | 27 |
|
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). |
| 28 | +Any contribution which contains commits that are not Signed-Off will not be accepted. |
24 | 29 |
|
25 | | -Follow 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. |
| 30 | +To sign off on a commit you simply use the `--signoff` (or `-s`) option when committing your changes: |
26 | 31 |
|
27 | | -***NOTE***: Only original source code from you and other people that have signed the CLA can be accepted into the main repository. |
| 32 | + $ git commit -s -m "Add cool feature." |
28 | 33 |
|
29 | | -### Contributing code |
| 34 | +This will append the following to your commit message: |
30 | 35 |
|
31 | | -If you have improvements to TensorFlow, send us your pull requests! For those |
32 | | -just getting started, Github has a |
33 | | -[how to](https://help.github.com/articles/using-pull-requests/). |
| 36 | + Signed-off-by: Your Name <your@email.com> |
34 | 37 |
|
35 | | -TensorFlow team members will be assigned to review your pull requests. Once the |
36 | | -pull requests are approved and pass continuous integration checks, a TensorFlow |
37 | | -team member will apply `ready to pull` label to your change. This means we are |
38 | | -working on getting your pull request submitted to our internal repository. After |
39 | | -the change has been submitted internally, your pull request will be merged |
40 | | -automatically on GitHub. |
| 38 | +By doing this you certify the below: |
41 | 39 |
|
42 | | -If you want to contribute, start working through the TensorFlow codebase, |
43 | | -navigate to the |
44 | | -[Github "issues" tab](https://github.com/tensorflow/tensorflow/issues) and start |
45 | | -looking through interesting issues. If you are not sure of where to start, then |
46 | | -start 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) |
48 | | -and then take a look at the |
49 | | -[issues with the "contributions welcome" label](https://github.com/tensorflow/tensorflow/labels/stat%3Acontributions%20welcome). |
50 | | -These are issues that we believe are particularly well suited for outside |
51 | | -contributions, often because we probably won't get to them right now. If you |
52 | | -decide to start on an issue, leave a comment so that other people know that |
53 | | -you're working on it. If you want to help out, but not alone, use the issue |
54 | | -comment thread to coordinate. |
| 40 | + Developer Certificate of Origin |
| 41 | + Version 1.1 |
55 | 42 |
|
56 | | -### Contribution guidelines and standards |
| 43 | + Copyright (C) 2004, 2006 The Linux Foundation and its contributors. |
| 44 | + 1 Letterman Drive |
| 45 | + Suite D4700 |
| 46 | + San Francisco, CA, 94129 |
57 | 47 |
|
58 | | -Before sending your pull request for |
59 | | -[review](https://github.com/tensorflow/tensorflow/pulls), |
60 | | -make sure your changes are consistent with the guidelines and follow the |
61 | | -TensorFlow coding style. |
| 48 | + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. |
62 | 49 |
|
63 | | -#### General guidelines and philosophy for contribution |
64 | 50 |
|
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 reached version 1 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. |
| 51 | + Developer's Certificate of Origin 1.1 |
87 | 52 |
|
88 | | -#### License |
| 53 | + By making a contribution to this project, I certify that: |
89 | 54 |
|
90 | | -Include a license at the top of new files. |
| 55 | + (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or |
91 | 56 |
|
92 | | -* [C/C++ license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/framework/op.cc#L1) |
93 | | -* [Python license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/python/ops/nn.py#L1) |
94 | | -* [Java license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/java/src/main/java/org/tensorflow/Graph.java#L1) |
95 | | -* [Go license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/go/operation.go#L1) |
96 | | -* [Bash license example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/ci_build/ci_sanity.sh#L2) |
97 | | -* [HTML license example](https://github.com/tensorflow/tensorboard/blob/master/tensorboard/components/tf_backend/tf-backend.html#L2) |
98 | | -* [JavaScript/TypeScript license example](https://github.com/tensorflow/tensorboard/blob/master/tensorboard/components/tf_backend/backend.ts#L1) |
| 57 | + (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or |
99 | 58 |
|
100 | | -Bazel BUILD files also need to include a license section, e.g., |
101 | | -[BUILD example](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/BUILD#L61). |
| 59 | + (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. |
102 | 60 |
|
103 | | -#### C++ coding style |
104 | | - |
105 | | -Changes to TensorFlow C++ code should conform to |
106 | | -[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). |
107 | | - |
108 | | -Use `clang-tidy` to check your C/C++ changes. To install `clang-tidy` on ubuntu:16.04, do: |
109 | | - |
110 | | -```bash |
111 | | -apt-get install -y clang-tidy |
112 | | -``` |
113 | | - |
114 | | -You can check a C/C++ file by doing: |
115 | | - |
116 | | - |
117 | | -```bash |
118 | | -clang-format <my_cc_file> --style=google > /tmp/my_cc_file.cc |
119 | | -diff <my_cc_file> /tmp/my_cc_file.cc |
120 | | -``` |
121 | | - |
122 | | -#### Python coding style |
123 | | - |
124 | | -Changes to TensorFlow Python code should conform to |
125 | | -[Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md) |
126 | | - |
127 | | -Use `pylint` to check your Python changes. To install `pylint` and |
128 | | -retrieve TensorFlow's custom style definition: |
129 | | - |
130 | | -```bash |
131 | | -pip install pylint |
132 | | -wget -O /tmp/pylintrc https://raw.githubusercontent.com/tensorflow/tensorflow/master/tensorflow/tools/ci_build/pylintrc |
133 | | -``` |
134 | | - |
135 | | -To check a file with `pylint`: |
136 | | - |
137 | | -```bash |
138 | | -pylint --rcfile=/tmp/pylintrc myfile.py |
139 | | -``` |
140 | | - |
141 | | -#### Coding style for other languages |
142 | | - |
143 | | -* [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) |
144 | | -* [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) |
145 | | -* [Google Shell Style Guide](https://google.github.io/styleguide/shell.xml) |
146 | | -* [Google Objective-C Style Guide](https://google.github.io/styleguide/objcguide.html) |
147 | | - |
148 | | -#### Running sanity check |
149 | | - |
150 | | -If you have Docker installed on your system, you can perform a sanity check on |
151 | | -your changes by running the command: |
152 | | - |
153 | | -```bash |
154 | | -tensorflow/tools/ci_build/ci_build.sh CPU tensorflow/tools/ci_build/ci_sanity.sh |
155 | | -``` |
156 | | - |
157 | | -This will catch most license, Python coding style and BUILD file issues that |
158 | | -may exist in your changes. |
159 | | - |
160 | | -#### Running unit tests |
161 | | - |
162 | | -There are two ways to run TensorFlow unit tests. |
163 | | - |
164 | | -1. Using tools and libraries installed directly on your system. |
165 | | - |
166 | | - Refer to the |
167 | | - [CPU-only developer Dockerfile](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/dockerfiles/dockerfiles/devel-cpu.Dockerfile) |
168 | | - and |
169 | | - [GPU developer Dockerfile](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/tools/dockerfiles/dockerfiles/devel-gpu.Dockerfile) |
170 | | - for the required packages. Alternatively, use the said |
171 | | - [Docker images](https://hub.docker.com/r/tensorflow/tensorflow/tags/), e.g., |
172 | | - `tensorflow/tensorflow:devel` and `tensorflow/tensorflow:devel-gpu` for |
173 | | - development to avoid installing the packages directly on your system (in |
174 | | - which case remember to change directory from `/root` to `/tensorflow` once |
175 | | - you get into the running container so `bazel` can find the `tensorflow` |
176 | | - workspace). |
177 | | - |
178 | | - Once you have the packages installed, you can run a specific unit test in |
179 | | - bazel by doing as follows: |
180 | | - |
181 | | - If the tests are to be run on GPU, add CUDA paths to LD_LIBRARY_PATH and add |
182 | | - the `cuda` option flag |
183 | | - |
184 | | - ```bash |
185 | | - export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/cuda/lib64:/usr/local/cuda/extras/CUPTI/lib64:$LD_LIBRARY_PATH" |
186 | | - |
187 | | - export flags="--config=opt --config=cuda -k" |
188 | | - ``` |
189 | | - |
190 | | - For example, to run all tests under tensorflow/python, do: |
191 | | - |
192 | | - ```bash |
193 | | - bazel test ${flags} //tensorflow/python/... |
194 | | - ``` |
195 | | - |
196 | | -2. Using [Docker](https://www.docker.com) and TensorFlow's CI scripts. |
197 | | -
|
198 | | - ```bash |
199 | | - # Install Docker first, then this will build and run cpu tests |
200 | | - tensorflow/tools/ci_build/ci_build.sh CPU bazel test //tensorflow/... |
201 | | - ``` |
202 | | -
|
203 | | - See |
204 | | - [TensorFlow Builds](https://github.com/tensorflow/tensorflow/tree/master/tensorflow/tools/ci_build) |
205 | | - for details. |
| 61 | + (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. |
0 commit comments