We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.
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.
This project follows Google's Open Source Community 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:
We also recommend that contributors take a look at the Tensorflow Contributing Guidelines.
We strongly recommend that contributors:
Initiate a conversation with the TFLM team via a TF Lite Micro Github issue 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.
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:
Write Good Pull Request Descriptions
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.
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 on how test code and writing small PRs should be reconciled.
We provide some additional guidelines for different categories of contributions.
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.
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 for more details of that process.
Please see the optimized kernel implementations guide.
Please see the new platform support guide for documentation on how to add TFLM support for your particular platform.
We support amd64-architecture development and testing on Ubuntu 22.04, although other OSes may work.
TFLM's primary build system is Bazel. Add Bazelisk as the bazel executable in your PATH (e.g., copy it to /usr/local/bin/bazel) to automatically download and run the correct Bazel version as specified in //.bazelversion.
Below are some tips that might be useful and improve the development experience.
Add the Refined GitHub plugin to make the github experience even better.
Code search the TfLite Micro codebase on Sourcegraph. And optionally install the plugin that enables GitHub integration.
Install Buildifier (e.g.) to format Bazel BUILD and .bzl files.
Install the latest clang and clang-format. For example, here is the what we do for the TFLM continuous integration Docker container.
Get a copy of cpplint or install it:
Install Pillow. For example, here is what we do for the TFLM continuous integration Docker container.
pip install cpplint
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
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"`
Make sure your code is lint-free.
cpplint `git ls-files -m`
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.
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
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
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.
GIthub CLI 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.
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>