From dabc133de019109918591870ac16ca551ea0e710 Mon Sep 17 00:00:00 2001 From: "A. Unique TensorFlower" Date: Tue, 22 May 2018 08:18:11 -0700 Subject: Contributing guidelines, style guide and README updates PiperOrigin-RevId: 197564905 --- tensorflow/contrib/autograph/CONTRIBUTING.md | 45 ++++++++++ tensorflow/contrib/autograph/README.md | 2 +- tensorflow/contrib/autograph/STYLE_GUIDE.md | 125 +++++++++++++++++++++++++++ 3 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 tensorflow/contrib/autograph/CONTRIBUTING.md create mode 100644 tensorflow/contrib/autograph/STYLE_GUIDE.md 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 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." -- cgit v1.2.3