Contribution docs

CODE_OF_CONDUCT.md

@@ -0,0 +1,75 @@
+# TensorFlow Code of Conduct
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+*   Using welcoming and inclusive language.
+*   Being respectful of differing viewpoints and experiences.
+*   Gracefully accepting constructive criticism.
+*   Focusing on what is best for the community.
+*   Showing empathy towards other community members.
+
+Examples of unacceptable behavior by participants include:
+
+*   The use of sexualized language or imagery and unwelcome sexual attention or
+    advances.
+*   Trolling, insulting/derogatory comments, and personal or political attacks.
+*   Public or private harassment.
+*   Publishing others' private information, such as a physical or electronic
+    address, without explicit permission.
+*   Conduct which could reasonably be considered inappropriate for the forum in
+    which it occurs.
+
+All TensorFlow forums and spaces are meant for professional interactions, and any behavior which could reasonably be considered inappropriate in a professional setting is unacceptable.
+
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+
+## Scope
+
+This Code of Conduct applies to all content on tensorflow.org, TensorFlow’s GitHub organization, or any other official TensorFlow web presence allowing for community interactions, as well as at all official TensorFlow events, whether offline or online.
+
+The Code of Conduct also applies within project spaces and in public spaces whenever an individual is representing TensorFlow or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed or de facto representative at an online or offline event.
+
+
+## Conflict Resolution
+
+Conflicts in an open source project can take many forms, from someone having a bad day and using harsh and hurtful language in the issue queue, to more serious instances such as sexist/racist statements or threats of violence, and everything in between.
+
+If the behavior is threatening or harassing, or for other reasons requires immediate escalation, please see below.
+
+However, for the vast majority of issues, we aim to empower individuals to first resolve conflicts themselves, asking for help when needed, and only after that fails to escalate further. This approach gives people more control over the outcome of their dispute.
+
+If you are experiencing or witnessing conflict, we ask you to use the following escalation strategy to address the conflict:
+
+1.  Address the perceived conflict directly with those involved, preferably in a
+    real-time medium.
+2.  If this fails, get a third party (e.g. a mutual friend, and/or someone with
+    background on the issue, but not involved in the conflict) to intercede.
+3.  If you are still unable to resolve the conflict, and you believe it rises to
+    harassment or another code of conduct violation, report it.
+
+## Reporting Violations
+
+Violations of the Code of Conduct can be reported to TensorFlow’s Project Stewards, Edd Wilder-James (ewj@google.com) and Sarah Novotny (sarahnovotny@google.com). The Project Steward will determine whether the Code of Conduct was violated, and will issue an appropriate sanction, possibly including a written warning or expulsion from the project, project sponsored spaces, or project forums. We ask that you make a good-faith effort to resolve your conflict via the conflict resolution policy before submitting a report.
+
+Violations of the Code of Conduct can occur in any setting, even those unrelated to the project. We will only consider complaints about conduct that has occurred within one year of the report.
+
+
+## Enforcement
+
+If the Project Stewards receive a report alleging a violation of the Code of Conduct, the Project Stewards will notify the accused of the report, and provide them an opportunity to discuss the report before a sanction is issued. The Project Stewards will do their utmost to keep the reporter anonymous. If the act is ongoing (such as someone engaging in harassment), or involves a threat to anyone's safety (e.g. threats of violence), the Project Stewards may issue sanctions without notice.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://contributor-covenant.org/version/1/4, and includes some aspects of the Geek Feminism Code of Conduct and the Drupal Code of Conduct.

CONTRIBUTING.md

@@ -1,30 +1,89 @@
-Want to contribute? Great! First, read this page (including the small print at the end).
-
-### Before you contribute
-
-Before we can use your code, you must sign the
-[Google Individual Contributor License Agreement]
-(https://cla.developers.google.com/about/google-individual)
-(CLA), which you can do online. The CLA is necessary mainly because you own the
-copyright to your changes, even after your contribution becomes part of our
-codebase, so we need your permission to use and distribute your code. We also
-need to be sure of various other things—for instance that you'll tell us if you
-know that your code infringes on other people's patents. You don't have to sign
-the CLA until after you've submitted your code for review and a member has
-approved it, but you must do it before we can put your code into our codebase.
-Before you start working on a larger contribution, you should get in touch with
-us first through the issue tracker with your idea so that we can help out and
-possibly guide you. Coordinating up front makes it much easier to avoid
-frustration later on.
-
-### Code reviews
+# Contributing
+
+Interested in contributing to TensorFlow Addons? We appreciate all kinds
+of help and are working to make this guide as comprehensive as possible.
+Please [let us know](https://github.com/tensorflow/addons/issues) if
+you think of something we could do to help lower the barrier to
+contributing.
+
+## Pull Requests
+
+We gladly welcome [pull requests](
+https://help.github.com/articles/about-pull-requests/).
+
+Before making any changes, we recommend opening an issue (if it
+doesn't already exist) and discussing your proposed changes. This will
+let us give you advice on the proposed changes. If the changes are
+minor, then feel free to make them without discussion.
+
+Want to contribute but not sure of what? Here are a few suggestions:
+1. Add a new example or tutorial. Located in [`tensorflow_addons/examples/`](tensorflow_addons/examples),
+  these are a great way to familiarize yourself and others with TF-Addons.
+2. Solve an [existing issue](https://github.com/tensorflow/addons/issues).
+  These range from low-level software bugs to higher-level design problems.
+  Check out the label [help wanted](https://github.com/tensorflow/addons/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
+
+All submissions, including submissions by project members, require
+review.
+
+## Requirements for New Contributions to the Repository
+The tensorflow/addons repository contains additional functionality
+fitting the following criteria:
+
+* The functionality is not otherwise available in TensorFlow
+* Addons have to be compatible with TensorFlow 2.x.
+* The addon conforms to the code and documentation standards
+* The addon is impactful to the community (e.g. an implementation used
+ in widely cited paper)
+ * Lastly, the functionality conforms to the contribution guidelines of
+ its API pattern:
+    * [Layers](tensorflow_addons/layers/README.md) |
+      [Optimizers](tensorflow_addons/optimizers/README.md) |
+      [Losses](tensorflow_addons/losses/README.md) |
+      Custom Ops
+
+**Note: New contributions often require team-members to read a research
+paper and understand how it fits into the TensorFlow community. This
+process can take longer than typical commit reviews so please bare with
+us**
+
+
+## Development Environment
+It is recommended that development is done in the latest
+`nightly-custom-op` docker image.
+```
+docker run --rm -it -v ${PWD}:/working_dir -w /working_dir tensorflow/tensorflow:nightly-custom-op /bin/bash
+```
+
+## Code Testing
+#### CI Testing
+We're in the process of setting up our nightly CI testing. Because this
+project will contain CUDA kernels, we need to make sure that the
+hardware will be available from our CI provider.
+
+#### Locally Testing
+```
+./configure.sh  # Links project with TensorFlow dependency
+
+bazel test -c opt -k \
+--test_timeout 300,450,1200,3600 \
+--test_output=errors \
+//tensorflow_addons/...
+```
+
+## Code Reviews
 
 All submissions, including submissions by project members, require review. We
 use Github pull requests for this purpose.
 
-### The small print
+## 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.
 
-Contributions made by corporations are covered by a different agreement than
-the one above, the
-[Software Grant and Corporate Contributor License Agreement]
-(https://cla.developers.google.com/about/google-corporate).
+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.

README.md

@@ -1,43 +1,82 @@
-**Addons** is a repository of contributions that conform to
+# TensorFlow Addons
+
+TensorFlow Addons is a repository of contributions that conform to
 well-established API patterns, but implement new functionality
 not available in core TensorFlow. TensorFlow natively supports
-a larger number of operators, layers, metrics, losses, and optimizers.
+a large number of operators, layers, metrics, losses, and optimizers.
 However, in a fast moving field like ML, there are many interesting new
 developments that cannot be integrated into core TensorFlow
-(because their broad applicability is not yet clear, or it is mostly used by a smaller
-subset of the community).
+(because their broad applicability is not yet clear, or it is mostly
+ used by a smaller subset of the community).
 
-# Scope
-The tensorflow/addons repository, will contain additional functionality fitting the following criteria:
+## Contents
+| Sub-Package    | Addon  | Reference                                  |
+|:----------------------- |:----------- |:---------------------------- |
+| addons.image | Transform |                                           |
+| addons.layers | Maxout | https://arxiv.org/abs/1302.4389             |
+| addons.layers | PoinareNormalize | https://arxiv.org/abs/1705.08039  |
+| addons.layers | WeightNormalization | https://arxiv.org/abs/1602.07868 |
+| addons.losses | TripletLoss | https://arxiv.org/abs/1503.03832       |
+| addons.optimizers | LazyAdamOptimizer | https://arxiv.org/abs/1412.6980 |
+| addons.text | SkipGrams | https://arxiv.org/abs/1301.3781 |
 
-* The functionality is not otherwise available in TensorFlow
-* The functionality conforms to an established API pattern in TensorFlow. For instance, it could be an additional subclass of an existing interface (new Layer, Metric, or Optimizer subclasses), or an additional Op or OpKernel implementation.
-* Addons have to be compatible with TensorFlow 2.x.
-* The addon conforms to the code and documentation standards defined by the group.
-* The addon is useful for a large number of users (e.g., an implementation used in widely cited paper, or a utility with broad applicability)
+## Core Concepts
 
+#### Standardized APIs
+User experience and project maintainability are core concepts in
+TF-Addons. In order to achieve these we require that our additions
+conform to established API patterns seen in core TensorFlow. Below is
+the list we adhere to:
 
-# Developing
 
-## Docker
-```
-docker run --rm -it -v ${PWD}:/working_dir -w /working_dir tensorflow/tensorflow:nightly-custom-op /bin/bash
-```
+1) [Layers](tensorflow_addons/layers/README.md)
+1) [Optimizers](tensorflow_addons/optimizers/README.md)
+1) [Losses](tensorflow_addons/losses/README.md)
+1) Custom Ops
+
+#### Periodic Evaluation
+Based on the nature of this repository, there will be contributions that
+in time become dated and unused. In order to keep the project
+maintainable, SIG-Addons will perform periodic reviews and deprecate
+contributions which will be slated for removal. More information will
+be available after we submit a formal request for comment.
+
+
+## Examples
+See [`tensorflow_addons/examples/`](tensorflow_addons/examples/)
+for end-to-end examples of various addons.
+
+## Installation
+#### Stable Builds
+`tensorflow-addons` will soon be available in PyPi.
+
+#### Installing from Source
+You can also install from source. This requires the [Bazel](
+https://bazel.build/) build system.
 
-## Packaging
 ```
-# In docker
-./configure.sh
+git clone https://github.com/tensorflow/addons.git
+cd addons
+
+# This script tells bazel where the tensorflow dependency can be found
+./configure.sh  # Links project with TensorFlow dependency
+
 bazel build build_pip_pkg
-bazel-bin/build_pip_pkg artifacts
+bazel-bin/build_pip_pkg artifact
+
+pip install artifacts/tensorflow_addons-*.whl
 ```
 
-A package file artifacts/tensorflow_addons-*.whl will be generated after a build is successful.
+## Contributing
+TF-Addons is a community led open source project. As such, the project
+depends on public contributions, bug-fixes, and documentation. Please
+see [CONTRIBUTING.md](CONTRIBUTING.md) for a guide on how to contribute.
+This project adheres to [TensorFlow's code of conduct](CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code.
 
+## Community
+* [Public Mailing List](https://groups.google.com/a/tensorflow.org/forum/#!forum/addons)
+* [SIG Monthly Meeting Notes](https://docs.google.com/document/d/1kxg5xIHWLY7EMdOJCdSGgaPu27a9YKpupUz2VTXqTJg)
 
-## Testing
-```
-# In docker
-./configure.sh
-bazel test //tensorflow_addons/...
-```
+## License
+[Apache License 2.0](LICENSE)

tensorflow_addons/layers/README.md

@@ -1,6 +1,24 @@
 # Addons - Layers
 
+## Contents
+| Layer  | Reference                                     |
+|:----------------------- |:-----------------------------|
+| Maxout | https://arxiv.org/abs/1302.4389               |
+| PoinareNormalize | https://arxiv.org/abs/1705.08039    |
+| WeightNormalization | https://arxiv.org/abs/1602.07868 |
 
-## Standard API
+
+## Contribution Guidelines
+#### Standard API
 In order to conform with the current API standard, all layers
-must inherit from either `keras.layers.Layer` or its subclasses.
+must:
+ * Inherit from either `keras.layers.Layer` or its subclasses.
+ * [Register as a keras global object](https://github.com/tensorflow/addons/blob/master/tensorflow_addons/utils/python/keras_utils.py)
+  so it can be serialized properly.
+
+#### Testing Requirements
+ * Simple unittests that demonstrate the layer is behaving as expected.
+ * When applicable, run all unittests with TensorFlow's
+  `@run_all_in_graph_and_eager_modes` decorator.
+ * Run `keras.testing_utils.layer_test` on the layer.
+

tensorflow_addons/losses/README.md

@@ -1,4 +1,21 @@
 # Addons - Losses
 
+## Contents
+| Loss  | Reference                                              |
+|:----------------------- |:-------------------------------------|
+| TripletLoss | https://arxiv.org/abs/1503.03832 |
 
-## Standard API
+
+## Contribution Guidelines
+#### Standard API
+In order to conform with the current API standard, all losses
+must:
+ * Inherit from `keras.losses.LossFunctionWrapper`.
+ * [Register as a keras global object](https://github.com/tensorflow/addons/blob/master/tensorflow_addons/utils/python/keras_utils.py)
+  so it can be serialized properly.
+
+#### Testing Requirements
+ * Simple unittests that demonstrate the loss is behaving as expected on
+ some set of known inputs and outputs.
+ * When applicable, run all tests with TensorFlow's
+ `@run_all_in_graph_and_eager_modes` decorator.

tensorflow_addons/optimizers/BUILD

@@ -9,7 +9,11 @@ py_library(
         "python/__init__.py",
         "python/lazy_adam_optimizer.py",
     ],
+    deps = [
+        "//tensorflow_addons/utils:utils_py",
+    ],
     srcs_version = "PY2AND3",
+
 )
 
 

tensorflow_addons/optimizers/README.md

@@ -1,3 +1,19 @@
 # Addons - Optimizers
 
-## Standard API
+## Contents
+| Optimizer  | Reference                                   |
+|:----------------------- |:-------------------------------|
+| LazyAdamOptimizer | https://arxiv.org/abs/1412.6980      |
+
+
+## Contribution Guidelines
+#### Standard API
+In order to conform with the current API standard, all optimizers
+must:
+ * Inherit from either `keras.optimizer_v2.OptimizerV2` or its subclasses.
+ * [Register as a keras global object](https://github.com/tensorflow/addons/blob/master/tensorflow_addons/utils/python/keras_utils.py)
+  so it can be serialized properly.
+
+#### Testing Requirements
+ * When applicable, run all tests with TensorFlow's
+ `@run_all_in_graph_and_eager_modes` decorator