Contributing guidelines, style guide and README updates

PiperOrigin-RevId: 197564905

3 files changed, 171 insertions, 1 deletions

diff --git a/tensorflow/contrib/autograph/CONTRIBUTING.md b/tensorflow/contrib/autograph/CONTRIBUTING.md
new file mode 100644
index 0000000000..a7a3fe1452
--- /dev/null
+++ b/tensorflow/contrib/autograph/CONTRIBUTING.md
@@ -0,0 +1,45 @@
+# How to Contribute
+
+We'd love to have your patches and contributions! Here are some guidelines. In general, we follow the [TensorFlow contributing guidelines](../../CONTRIBUTING.md), but have some [AutoGraph-specific style guidelines](STYLE_GUIDE.md). More details below.
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution;
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult [GitHub
+Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
+
+After a pull request is approved, we merge it. Note our merging process differs
+from GitHub in that we pull and submit the change into an internal version
+control system. This system automatically pushes a git commit to the GitHub
+repository (with credit to the original author) and closes the pull request.
+
+## Style
+
+See the [TensorFlow AutoGraph style guide](STYLE_GUIDE.md).
+
+## Unit tests
+
+Please include unit tests when contributing new features ([example here](converters/continue_statements_test.py)), as they help to a) prove that your code works correctly, and b) guard against future breaking
+changes to lower the maintenance cost.
+It's also helpful to check that any
+changes you propose do not break existing unit tests. You can run tests using the command,
+
+```shell
+bazel test --config=opt --copt=-O3 --copt=-march=native \
+  //tensorflow/contrib/autograph/...
+```
+
+from the root of the `tensorflow` repository. For more details see the [main TensorFlow Contributing File](../../CONTRIBUTING.md)
diff --git a/tensorflow/contrib/autograph/README.md b/tensorflow/contrib/autograph/README.md
index 0ba99c396f..674859bed4 100644
--- a/tensorflow/contrib/autograph/README.md
+++ b/tensorflow/contrib/autograph/README.md
@@ -1,6 +1,6 @@
 # AutoGraph
 
-IMPORTANT: AutoGraph is pre-alpha, under active development. Expect rough edges and bugs, but if you try it, we appreciate early feedback!
+IMPORTANT: AutoGraph is alpha software, and under active development. Expect rough edges and bugs, but if you try it, we appreciate early feedback! We'd also love contributions ([please see our contributing guidelines](CONTRIBUTING.md) and our [style guide](STYLE_GUIDE.md)).
 
 AutoGraph is a Python to TensorFlow compiler.
 
diff --git a/tensorflow/contrib/autograph/STYLE_GUIDE.md b/tensorflow/contrib/autograph/STYLE_GUIDE.md
new file mode 100644
index 0000000000..5618ec3e34
--- /dev/null
+++ b/tensorflow/contrib/autograph/STYLE_GUIDE.md
@@ -0,0 +1,125 @@
+# TensorFlow AutoGraph Style Guide
+
+This page contains style decisions that both developers and users of TensorFlow
+AutoGraph should follow to increase the readability of their code, reduce the
+number of errors, and promote consistency. We borrow many style principles from the TensorFlow Probability style guide.
+
+## TensorFlow Style
+
+Follow the [TensorFlow style
+guide](https://www.tensorflow.org/community/style_guide) and [documentation
+guide](https://www.tensorflow.org/community/documentation). Below are additional
+TensorFlow conventions not noted in those guides. In the future, these noted
+conventions may be moved upstream.
+
+1.  The name is TensorFlow, not Tensorflow.
+2.  The name is AutoGraph, not Autograph.
+
+## TensorFlow Code of Conduct
+Please review and follow the [TensorFlow Code of Conduct](../../CODE_OF_CONDUCT.md).
+
+## TensorFlow AutoGraph Style
+
+Below are TensorFlow AutoGraph-specific conventions. In the event of conflict,
+it supercedes all previous conventions.
+
+1.  __Importing submodule aliases.__ Use the Pythonic style 
+`from tensorflow.contrib.autograph.converters import ifexp` and `from tensorflow.contrib import autograph as ag`.
+
+2.  __Examples in Docstrings.__ Write a `#### Examples` subsection below `Args`,
+    `Returns`, `Raises`, etc. to illustrate examples. If the docstring's last
+    line is a fence bracket (\`\`\`) closing a code snippet, add an empty line
+    before closing the docstring with \"\"\". This properly displays the code
+    snippet.
+
+    Justification: Users regularly need to remind themselves of args and
+    semantics. But rarely look at examples more than the first time. But since
+    examples are usually long (which is great!) it means they have to do a lot
+    of annoying scrolling ...unless Examples follow Args/Returns/Raises.
+
+3.  __Citations in Docstrings.__ Write a `#### References` subsection at the
+    bottom of any docstring with citations. Use ICLR’s bibliography style to
+    write references; for example, order entries by the first author's last
+    name. Add a link to the paper if the publication is open source (ideally,
+    arXiv).
+
+    Write in-paragraph citations in general, e.g., [(Tran and Blei, 2018)][1].
+    Write in-text citations when the citation is a noun, e.g., [Tran and Blei
+    (2018)][1]. Write citations with more than two authors using et al., e.g.,
+    [(Tran et al., 2018)][1]. Separate multiple citations with semicolon, e.g.,
+    ([Tran and Blei, 2018][1]; [Gelman and Rubin, 1992][2]).
+
+    Examples:
+
+    ```none
+    #### References
+
+    # technical report
+    [1]: Tony Finch. Incremental calculation of weighted mean and variance.
+         _Technical Report_, 2009.
+         http://people.ds.cam.ac.uk/fanf2/hermes/doc/antiforgery/stats.pdf
+
+    # journal
+    [2]: Andrew Gelman and Donald B. Rubin. Inference from Iterative Simulation
+         Using Multiple Sequences. _Statistical Science_, 7(4):457-472, 1992.
+
+    # arXiv preprint
+    # use "et al." for papers with too many authors to maintain
+    [3]: Aaron van den Oord et al. Parallel WaveNet: Fast High-Fidelity Speech
+         Synthesis. _arXiv preprint arXiv:1711.10433_, 2017.
+         https://arxiv.org/abs/1711.10433
+
+    # conference
+    [4]: Yeming Wen, Paul Vicol, Jimmy Ba, Dustin Tran, and Roger Grosse.
+         Flipout: Efficient Pseudo-Independent Weight Perturbations on
+         Mini-Batches. In _International Conference on Learning
+         Representations_, 2018.
+         https://arxiv.org/abs/1803.04386
+    ```
+
+4.  When doing float math over literals eg use `1.` instead of `1` or `1.0`.
+
+    *   Using `1.` is another line of defense against an automatic casting
+        mistake. (Using `1.0` is also such a defense but is not minimal.)
+
+5.  Prefer using named args for functions' 2nd args onward.
+
+    *   Definitely use named args for 2nd args onward in docstrings.
+
+9.  Avoid LaTeX in docstrings.
+
+    *   It is not rendered in many (if not most) editors and can be hard to read
+        for both LaTeX experts and non-experts.
+
+10. Write docstring and comment math using ASCII friendly notation; python using
+    operators. E.g., `x**2` better than `x^2`, `x[i, j]` better than `x_{i,j}`,
+    `sum{ f(x[i]) : i=1...n }` better than `\sum_{i=1}^n f(x_i)` `int{sin(x) dx:
+    x in [0, 2 pi]}` better than `\int_0^{2\pi} sin(x) dx`.
+
+    *   The more we stick to python style, the more someone can
+        copy/paste/execute.
+    *   Python style is usually easier to read as ASCII.
+
+11. All public functions require docstrings with: one line description, Args,
+    Returns, Raises (if raises exceptions).
+
+    *   Returns docstrings should be in the same format as Args, eg, of the form
+        "name: Description." Part of the rationale is that we are suggesting a
+        reasonable variable name for the returned object(s).
+
+12. Regard `*args` and/or `**kwargs` as features of last resort.
+
+    *   Keyword arguments make the intention of a function call more clear.
+    *   [Possible exceptions for
+        `kwargs`](https://stackoverflow.com/questions/1415812/why-use-kwargs-in-python-what-are-some-real-world-advantages-over-using-named).
+
+18. The `__init__.py` file for modules should use TensorFlow's
+    `remove_undocumented` feature, which seals the module's methods.
+
+21. Use `"{}".format()` rather than `"" %` for string formatting.
+
+    Justification: [PEP 3101](https://www.python.org/dev/peps/pep-3101/) and
+    [Python official
+    tutorials](https://docs.python.org/3.2/tutorial/inputoutput.html#old-string-formatting):
+    "...this old style of formatting will eventually be removed from the
+    language, str.format() should generally be used."