CONTRIBUTING.md - 3p/tensorflow/tflite-micro - Git at Google

 <!--
 emi-automated TOC generation with instructions from
 https://github.com/ekalinin/github-markdown-toc#auto-insert-and-update-toc
 -->

 <!--ts-->
    * [How to Contribute](#how-to-contribute)
       * [Contributor License Agreement](#contributor-license-agreement)
       * [Community Guidelines](#community-guidelines)
    * [Code Contribution Guidelines](#code-contribution-guidelines)
       * [General Pull Request Guidelines](#general-pull-request-guidelines)
       * [Guidelines for Specific Contribution Categories](#guidelines-for-specific-contribution-categories)
          * [Bug Fixes](#bug-fixes)
          * [Reference Kernel Implementations](#reference-kernel-implementations)
          * [Optimized Kernel Implementations](#optimized-kernel-implementations)
          * [New Target / Platform / IDE / Examples](#new-target--platform--ide--examples)
    * [Development Workflow Notes](#development-workflow-notes)
       * [Initial Setup](#initial-setup)
       * [Before submitting your PR](#before-submitting-your-pr)
       * [During the PR review](#during-the-pr-review)
       * [Reviewer notes](#reviewer-notes)
       * [Python notes](#python-notes)
    * [Continuous Integration System](#continuous-integration-system)

 <!-- Added by: advaitjain, at: Thu 16 Sep 2021 11:43:42 AM PDT -->

 <!--te-->

 # How to Contribute

 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.

 ## Contributor License Agreement

 Contributions to this project must be accompanied by a Contributor License
 Agreement (CLA). 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.

 ## Community Guidelines

 This project follows
 [Google's Open Source Community Guidelines](https://opensource.google/conduct/).

 # Code Contribution Guidelines

 We provide some general guidelines with the goal of enabling community
 contributions while still maintaining code health, maintainability, and
 consistency in style.

 Please note that while these guidelines may seem onerous to some developers,
 they are derived from Google's software engineering best practices.

 Before we describe project-specific guidelines, we recommend that external
 contributors read these tips from the Google Testing Blog:

 *   [Code Health: Providing Context with Commit Messages and Bug Reports](https://testing.googleblog.com/2017/09/code-health-providing-context-with.html)
 *   [Code Health: Understanding Code In Review](https://testing.googleblog.com/2018/05/code-health-understanding-code-in-review.html)
 *   [Code Health: Too Many Comments on Your Code Reviews?](https://testing.googleblog.com/2017/06/code-health-too-many-comments-on-your.html)
 *   [Code Health: To Comment or Not to Comment?](https://testing.googleblog.com/2017/07/code-health-to-comment-or-not-to-comment.html)

 We also recommend that contributors take a look at the
 [Tensorflow Contributing Guidelines](https://github.com/tensorflow/tensorflow/blob/master/CONTRIBUTING.md).

 ## General Pull Request Guidelines

 We strongly recommend that contributors:

 1.  Initiate a conversation with the TFLM team via a
     [TF Lite Micro Github issue](https://github.com/tensorflow/tensorflow/issues/new?labels=comp%3Amicro&template=70-tflite-micro-issue.md)
     as early as possible.

     *   This enables us to give guidance on how to proceed, prevent duplicated
         effort and also point to alternatives as well as context if we are not
         able to accept a particular contribution at a given time.

     *   Ideally, you should make an issue ***before*** starting to work on a
         pull request and provide context on both what you want to contribute and
         why.

 1.  Once step 1. is complete and it is determined that a PR from an external
     contributor is the way to go, please follow these guidelines from
     [Google's Engineering Practices documentation](https://google.github.io/eng-practices/):

     *   [Send Small Pull Requests](https://google.github.io/eng-practices/review/developer/small-cls.html)

         *   If a pull request is doing more than one thing, the reviewer will
             request that it be broken up into two or more PRs.

     *   [Write Good Pull Request Descriptions](https://google.github.io/eng-practices/review/developer/cl-descriptions.html)

         *   We require that all PR descriptions link to the GitHub issue
             created in step 1 via the text `BUG=#nn` on a line by itself [^1]. This
             is enforced by CI.

             [^1]: This despite GitHub having additional forms of
             [linked references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls).

 1.  Unit tests are critical to a healthy codebase. PRs without tests should be
     the exception rather than the norm. And contributions to improve, simplify,
     or make the unit tests more exhaustive are welcome! Please refer to
     [this guideline](https://google.github.io/eng-practices/review/developer/small-cls.html#test_code)
     on how test code and writing small PRs should be reconciled.

 ## Guidelines for Specific Contribution Categories

 We provide some additional guidelines for different categories of contributions.

 ### Bug Fixes

 Pull requests that fix bugs are always welcome and often uncontroversial, unless
 there is a conflict between different requirements from the platform, or if
 fixing a bug needs a bigger architectural change.

 1.  Create a [Github issue](https://github.com/tensorflow/tflite-micro/issues/new/choose)
     to determine the scope of the bug fix.
 1.  Send a PR (if that is determined to be the best path forward).
 1.  Bugfix PRs should be accompanied by a test case that fails prior to the fix
     and passes with the fix. This validates that the fix works as expected, and
     helps prevent future regressions.

 ### Reference Kernel Implementations

 Pull requests that port reference kernels from TF Lite Mobile to TF Lite Micro
 are welcome once we have context from the contributor on why the additional
 kernel is needed.

 Please see the [reference kernel porting guide](tensorflow/lite/micro/docs/porting_reference_ops.md)
 for more details of that process.

 ### Optimized Kernel Implementations
 Please see the [optimized kernel implementations guide](tensorflow/lite/micro/docs/optimized_kernel_implementations.md).

 ### New Target / Platform / IDE / Examples

 Please see the [new platform support guide](tensorflow/lite/micro/docs/new_platform_support.md)
 for documentation on how to add TFLM support for your particular platform.


 # Development Workflow Notes

 ## Initial Setup

 Below are some tips that might be useful and improve the development experience.

 * Add the [Refined GitHub](https://github.com/sindresorhus/refined-github)
   plugin to make the github experience even better.

 * Code search the [TfLite Micro codebase](https://sourcegraph.com/github.com/tensorflow/tflite-micro@main)
   on Sourcegraph. And optionally install the [plugin that enables GitHub integration](https://docs.sourcegraph.com/integration/github#github-integration-with-sourcegraph).

 * Install [bazel](ci/install_bazelisk.sh) and [buildifier](ci/install_buildifier.sh).

 * Install the latest clang and clang-format. For example, [here](ci/Dockerfile.micro)
   is the what we do for the TFLM continuous integration Docker container.

 * Get a copy of [cpplint](https://github.com/google/styleguide/tree/gh-pages/cpplint)
   or install it:

 * Install Pillow and Wave.  For example, [here](ci/Dockerfile.micro) is what we
   do for the TFLM continuous integration Docker container.

   ```
   pip install cpplint
   ```

 * [yapf](https://github.com/google/yapf/) should be used for formatting Python
   code. For example:

   ```
   pip install yapf
   yapf log_parser.py -i --style='{based_on_style: pep8, indent_width: 2}'
   ```

 * Add a git hook to check for code style etc. prior to creating a pull request:
   ```
   cp tensorflow/lite/micro/tools/dev_setup/pre-push.tflm .git/hooks/pre-push
   ```

 ## Before submitting your PR

 1.  Run in-place clang-format on all the files that are modified in your git
     tree with

     ```
     clang-format -i -style=google `git ls-files -m | grep "\.cc"`
     clang-format -i -style=google `git ls-files -m | grep "\.h"`
     ```

 1.  Make sure your code is lint-free.

     ```
     cpplint `git ls-files -m`
     ```

 1.  Run all the tests for x86, and any other platform that you are modifying.

     ```
     tensorflow/lite/micro/tools/ci_build/test_x86_default.sh
     ```

     Please check the READMEs in the optimized kernel directories for specific
     instructions.

 1.  Sometimes, bugs are caught by the sanitizers that can go unnoticed
     via the Makefile. To run a test with the different sanitizers, use the
     following commands (replace `micro_interpreter_test` with the target that you
     want to test:

     ```
     CC=clang bazel run --config=asan tensorflow/lite/micro:micro_interpreter_test
     CC=clang bazel run --config=msan tensorflow/lite/micro:micro_interpreter_test
     CC=clang bazel run --config=ubsan tensorflow/lite/micro:micro_interpreter_test
     ```

 ## During the PR review

 1.  Do not change the git version history.

     *   Always merge upstream/main (***do not rebase***) and no force-pushes
         please.

     *   Having an extra merge commit is ok as the github review tool handles
         that gracefully.

     Assuming that you forked tensorflow and added a remote called upstream with:

     ```
     git remote add upstream https://github.com/tensorflow/tflite-micro.git
     ```

     Fetch the latest changes from upstream and merge into your local branch.

     ```
     git fetch upstream
     git merge upstream/main
     ```

     In case of a merge conflict, resolve via:

     ```
     git mergetool

     # Use your favorite diff tools (e.g. meld) to resolve the conflicts.

     git add <files that were manually resolved>

     git commit
     ```

 1.  If a force push seems to be the only path forward, please stop and let your
     PR reviewer know ***before*** force pushing. We will attempt to do the merge
     for you. This will also help us better understand in what conditions a
     force-push may be unavoidable.

 ## Reviewer notes

 *   [GIthub CLI](https://cli.github.com) can be useful to quickly checkout a PR
     to test locally.

     `gh pr checkout <PR number>`

 *   Google engineers on the Tensorflow team will have the permissions to push
     edits to most PRs. This can be useful to make some small fixes as a result
     of errors due to internal checks that are not easily reproducible via
     github.

     One example of this is
     [this comment](https://github.com/tensorflow/tensorflow/pull/38634#issuecomment-683190474).

     And a sketch of the steps:

     ```
     git remote add <remote_name> git@github.com:<PR author>/tflite-micro.git
     git fetch <remote_name>

     git checkout -b <local-branch-name> <remote_name>/<PR branch name>

     # make changes and commit to local branch

     # push changes to remove branch

     git push <remote_name> <PR branch name>

     # remove the temp remote to clean up your git environment.

     git remote rm <remote_name>
     ```

 ## Python notes

 *   [TFLM Python guide](docs/python.md)

 # Continuous Integration System
   * Some [additional documentation](docs/continuous_integration.md) on the TFLM CI.
	<!--
	emi-automated TOC generation with instructions from
	https://github.com/ekalinin/github-markdown-toc#auto-insert-and-update-toc
	-->

	<!--ts-->
	* [How to Contribute](#how-to-contribute)
	* [Contributor License Agreement](#contributor-license-agreement)
	* [Community Guidelines](#community-guidelines)
	* [Code Contribution Guidelines](#code-contribution-guidelines)
	* [General Pull Request Guidelines](#general-pull-request-guidelines)
	* [Guidelines for Specific Contribution Categories](#guidelines-for-specific-contribution-categories)
	* [Bug Fixes](#bug-fixes)
	* [Reference Kernel Implementations](#reference-kernel-implementations)
	* [Optimized Kernel Implementations](#optimized-kernel-implementations)
	* [New Target / Platform / IDE / Examples](#new-target--platform--ide--examples)
	* [Development Workflow Notes](#development-workflow-notes)
	* [Initial Setup](#initial-setup)
	* [Before submitting your PR](#before-submitting-your-pr)
	* [During the PR review](#during-the-pr-review)
	* [Reviewer notes](#reviewer-notes)
	* [Python notes](#python-notes)
	* [Continuous Integration System](#continuous-integration-system)

	<!-- Added by: advaitjain, at: Thu 16 Sep 2021 11:43:42 AM PDT -->

	<!--te-->

	# How to Contribute

	We'd love to accept your patches and contributions to this project. There are
	just a few small guidelines you need to follow.

	## Contributor License Agreement

	Contributions to this project must be accompanied by a Contributor License
	Agreement (CLA). 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.

	## Community Guidelines

	This project follows
	[Google's Open Source Community Guidelines](https://opensource.google/conduct/).

	# Code Contribution Guidelines

	We provide some general guidelines with the goal of enabling community
	contributions while still maintaining code health, maintainability, and
	consistency in style.

	Please note that while these guidelines may seem onerous to some developers,
	they are derived from Google's software engineering best practices.

	Before we describe project-specific guidelines, we recommend that external
	contributors read these tips from the Google Testing Blog:

	* [Code Health: Providing Context with Commit Messages and Bug Reports](https://testing.googleblog.com/2017/09/code-health-providing-context-with.html)
	* [Code Health: Understanding Code In Review](https://testing.googleblog.com/2018/05/code-health-understanding-code-in-review.html)
	* [Code Health: Too Many Comments on Your Code Reviews?](https://testing.googleblog.com/2017/06/code-health-too-many-comments-on-your.html)
	* [Code Health: To Comment or Not to Comment?](https://testing.googleblog.com/2017/07/code-health-to-comment-or-not-to-comment.html)

	We also recommend that contributors take a look at the
	[Tensorflow Contributing Guidelines](https://github.com/tensorflow/tensorflow/blob/master/CONTRIBUTING.md).

	## General Pull Request Guidelines

	We strongly recommend that contributors:

	1. Initiate a conversation with the TFLM team via a
	[TF Lite Micro Github issue](https://github.com/tensorflow/tensorflow/issues/new?labels=comp%3Amicro&template=70-tflite-micro-issue.md)
	as early as possible.

	* This enables us to give guidance on how to proceed, prevent duplicated
	effort and also point to alternatives as well as context if we are not
	able to accept a particular contribution at a given time.

	* Ideally, you should make an issue *before* starting to work on a
	pull request and provide context on both what you want to contribute and
	why.

	1. Once step 1. is complete and it is determined that a PR from an external
	contributor is the way to go, please follow these guidelines from
	[Google's Engineering Practices documentation](https://google.github.io/eng-practices/):

	* [Send Small Pull Requests](https://google.github.io/eng-practices/review/developer/small-cls.html)

	* If a pull request is doing more than one thing, the reviewer will
	request that it be broken up into two or more PRs.

	* [Write Good Pull Request Descriptions](https://google.github.io/eng-practices/review/developer/cl-descriptions.html)

	* We require that all PR descriptions link to the GitHub issue
	created in step 1 via the text `BUG=#nn` on a line by itself [^1]. This
	is enforced by CI.

	[^1]: This despite GitHub having additional forms of
	[linked references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls).

	1. Unit tests are critical to a healthy codebase. PRs without tests should be
	the exception rather than the norm. And contributions to improve, simplify,
	or make the unit tests more exhaustive are welcome! Please refer to
	[this guideline](https://google.github.io/eng-practices/review/developer/small-cls.html#test_code)
	on how test code and writing small PRs should be reconciled.

	## Guidelines for Specific Contribution Categories

	We provide some additional guidelines for different categories of contributions.

	### Bug Fixes

	Pull requests that fix bugs are always welcome and often uncontroversial, unless
	there is a conflict between different requirements from the platform, or if
	fixing a bug needs a bigger architectural change.

	1. Create a [Github issue](https://github.com/tensorflow/tflite-micro/issues/new/choose)
	to determine the scope of the bug fix.
	1. Send a PR (if that is determined to be the best path forward).
	1. Bugfix PRs should be accompanied by a test case that fails prior to the fix
	and passes with the fix. This validates that the fix works as expected, and
	helps prevent future regressions.

	### Reference Kernel Implementations

	Pull requests that port reference kernels from TF Lite Mobile to TF Lite Micro
	are welcome once we have context from the contributor on why the additional
	kernel is needed.

	Please see the [reference kernel porting guide](tensorflow/lite/micro/docs/porting_reference_ops.md)
	for more details of that process.

	### Optimized Kernel Implementations
	Please see the [optimized kernel implementations guide](tensorflow/lite/micro/docs/optimized_kernel_implementations.md).

	### New Target / Platform / IDE / Examples

	Please see the [new platform support guide](tensorflow/lite/micro/docs/new_platform_support.md)
	for documentation on how to add TFLM support for your particular platform.


	# Development Workflow Notes

	## Initial Setup

	Below are some tips that might be useful and improve the development experience.

	* Add the [Refined GitHub](https://github.com/sindresorhus/refined-github)
	plugin to make the github experience even better.

	* Code search the [TfLite Micro codebase](https://sourcegraph.com/github.com/tensorflow/tflite-micro@main)
	on Sourcegraph. And optionally install the [plugin that enables GitHub integration](https://docs.sourcegraph.com/integration/github#github-integration-with-sourcegraph).

	* Install [bazel](ci/install_bazelisk.sh) and [buildifier](ci/install_buildifier.sh).

	* Install the latest clang and clang-format. For example, [here](ci/Dockerfile.micro)
	is the what we do for the TFLM continuous integration Docker container.

	* Get a copy of [cpplint](https://github.com/google/styleguide/tree/gh-pages/cpplint)
	or install it:

	* Install Pillow and Wave. For example, [here](ci/Dockerfile.micro) is what we
	do for the TFLM continuous integration Docker container.

	```
	pip install cpplint
	```

	* [yapf](https://github.com/google/yapf/) should be used for formatting Python
	code. For example:

	```
	pip install yapf
	yapf log_parser.py -i --style='{based_on_style: pep8, indent_width: 2}'
	```

	* Add a git hook to check for code style etc. prior to creating a pull request:
	```
	cp tensorflow/lite/micro/tools/dev_setup/pre-push.tflm .git/hooks/pre-push
	```

	## Before submitting your PR

	1. Run in-place clang-format on all the files that are modified in your git
	tree with

	```
	clang-format -i -style=google `git ls-files -m \| grep "\.cc"`
	clang-format -i -style=google `git ls-files -m \| grep "\.h"`
	```

	1. Make sure your code is lint-free.

	```
	cpplint `git ls-files -m`
	```

	1. Run all the tests for x86, and any other platform that you are modifying.

	```
	tensorflow/lite/micro/tools/ci_build/test_x86_default.sh
	```

	Please check the READMEs in the optimized kernel directories for specific
	instructions.

	1. Sometimes, bugs are caught by the sanitizers that can go unnoticed
	via the Makefile. To run a test with the different sanitizers, use the
	following commands (replace `micro_interpreter_test` with the target that you
	want to test:

	```
	CC=clang bazel run --config=asan tensorflow/lite/micro:micro_interpreter_test
	CC=clang bazel run --config=msan tensorflow/lite/micro:micro_interpreter_test
	CC=clang bazel run --config=ubsan tensorflow/lite/micro:micro_interpreter_test
	```

	## During the PR review

	1. Do not change the git version history.

	* Always merge upstream/main (*do not rebase*) and no force-pushes
	please.

	* Having an extra merge commit is ok as the github review tool handles
	that gracefully.

	Assuming that you forked tensorflow and added a remote called upstream with:

	```
	git remote add upstream https://github.com/tensorflow/tflite-micro.git
	```

	Fetch the latest changes from upstream and merge into your local branch.

	```
	git fetch upstream
	git merge upstream/main
	```

	In case of a merge conflict, resolve via:

	```
	git mergetool

	# Use your favorite diff tools (e.g. meld) to resolve the conflicts.

	git add <files that were manually resolved>

	git commit
	```

	1. If a force push seems to be the only path forward, please stop and let your
	PR reviewer know *before* force pushing. We will attempt to do the merge
	for you. This will also help us better understand in what conditions a
	force-push may be unavoidable.

	## Reviewer notes

	* [GIthub CLI](https://cli.github.com) can be useful to quickly checkout a PR
	to test locally.

	`gh pr checkout <PR number>`

	* Google engineers on the Tensorflow team will have the permissions to push
	edits to most PRs. This can be useful to make some small fixes as a result
	of errors due to internal checks that are not easily reproducible via
	github.

	One example of this is
	[this comment](https://github.com/tensorflow/tensorflow/pull/38634#issuecomment-683190474).

	And a sketch of the steps:

	```
	git remote add <remote_name> git@github.com:<PR author>/tflite-micro.git
	git fetch <remote_name>

	git checkout -b <local-branch-name> <remote_name>/<PR branch name>

	# make changes and commit to local branch

	# push changes to remove branch

	git push <remote_name> <PR branch name>

	# remove the temp remote to clean up your git environment.

	git remote rm <remote_name>
	```

	## Python notes

	* [TFLM Python guide](docs/python.md)

	# Continuous Integration System
	* Some [additional documentation](docs/continuous_integration.md) on the TFLM CI.