Contribute to the TensorFlow code

Whether you are adding a loss function, improving test coverage, or writing an RFC for a major design change, this portion of the contributor guide will help you get started. Thank you for your work and interest in improving TensorFlow.

Before you get started

Before you contribute source code to a TensorFlow project, please review the CONTRIBUTING.md file in the GitHub repo of the project. For example, see the CONTRIBUTING.md file in the core TensorFlow repo. All code contributors are required to sign a Contributor License Agreement (CLA).

To avoid duplicating work, please review current or proposed RFCs and contact the developers on the TensorFlow forums (developers@tensorflow.org) before you start work on a non-trivial feature. We are somewhat selective when deciding to add new functionality, and the best way to contribute and help the project is to work on known issues.

Issues for new contributors

New contributors should look for the following tags when searching for a first contribution to the TensorFlow code base. We strongly recommend that new contributors tackle “good first issue” and "contributions welcome" projects first; this helps the contributor become familiar with the contribution workflow, and for the core devs to become acquainted with the contributor.

If you are interested in recruiting a team to help tackle a large-scale problem or a new feature, please email the developers@ group and review our current list of RFCs.

Code review

New features, bug fixes, and any other changes to the code base are subject to code review.

Reviewing code contributed to the project as pull requests is a crucial component of TensorFlow development. We encourage anyone to start reviewing code submitted by other developers, especially if the feature is something that you are likely to use.

Here are some questions to keep in mind during the code review process:

  • Do we want this in TensorFlow? Is it likely to be used? Do you, as a TensorFlow user, like the change and intend to use it? Is this change in the scope of TensorFlow? Will the cost of maintaining a new feature be worth its benefits?
  • Is the code consistent with the TensorFlow API? Are public functions, classes, and parameters well-named and intuitively designed?

  • Does it include documentation? Are all public functions, classes, parameters, return types, and stored attributes named according to TensorFlow conventions and clearly documented? Is new functionality described in TensorFlow's documentation and illustrated with examples, whenever possible? Does the documentation render properly?

  • Is the code human-readable? Is it low on redundancy? Should variable names be improved for clarity or consistency? Should comments be added? Should any comments be removed as unhelpful or extraneous?

  • Is the code efficient? Could it be rewritten easily to run more efficiently?

  • Is the code backwards compatible with previous versions of TensorFlow?

  • Will the new code add new dependencies on other libraries?

Test and improve test coverage

High-quality unit testing is a corner-stone of the TensorFlow development process. For this purpose, we use Docker images. The test functions are appropriately named, and are responsible for checking the validity of algorithms as well as different options of the code.

All new features and bug fixes must include adequate test coverage. We also welcome contributions of new test cases or improvements to existing tests. If you discover that our existing tests are not complete — even if that is not currently causing a bug — please file an issue and, if possible, a pull request.

For the specific details of testing procedures in each TensorFlow project, see the README.md and CONTRIBUTING.md files in the project repo on GitHub.

Of particular concerns in adequate testing:

  • Is every public function and class tested?
  • Are a reasonable set of parameters, their values, value types, and combinations tested?
  • Do the tests validate that the code is correct, and that it is doing what the documentation says the code is intended to do?
  • If the change is a bug fix, is a non-regression test included?
  • Do the tests pass the continuous integration build?
  • Do the tests cover every line of code? If not, are the exceptions reasonable and explicit?

If you find any problems, please consider helping the contributor understand those problems and resolve them.

Improve error messages or logs

We welcome contributions that improve error messages and logging.

Contribution workflow

Code contributions—bug fixes, new development, test improvement—all follow a GitHub-centered workflow. To participate in TensorFlow development, set up a GitHub account. Then:

  1. Fork the repo you plan to work on. Go to the project repo page and use the Fork button. This will create a copy of the repo, under your username. (For more details on how to fork a repository see this guide.)

  2. Clone down the repo to your local system.

    $ git clone git@github.com:your-user-name/project-name.git

  3. Create a new branch to hold your work.

    $ git checkout -b new-branch-name

  4. Work on your new code. Write and run tests.

  5. Commit your changes.

    $ git add -A

    $ git commit -m "commit message here"

  6. Push your changes to your GitHub repo.

    $ git push origin branch-name

  7. Open a Pull Request (PR). Go to the original project repo on GitHub. There will be a message about your recently pushed branch, asking if you would like to open a pull request. Follow the prompts, compare across repositories, and submit the PR. This will send an email to the committers. You may want to consider sending an email to the mailing list for more visibility. (For more details, see the GitHub guide on PRs.

  8. Maintainers and other contributors will review your PR. Please participate in the conversation, and try to make any requested changes. Once the PR is approved, the code will be merged.

Before working on your next contribution, make sure your local repository is up to date.

  1. Set the upstream remote. (You only have to do this once per project, not every time.)

    $ git remote add upstream git@github.com:tensorflow/project-repo-name

  2. Switch to the local master branch.

    $ git checkout master

  3. Pull down the changes from upstream.

    $ git pull upstream master

  4. Push the changes to your GitHub account. (Optional, but a good practice.)

    $ git push origin master

  5. Create a new branch if you are starting new work.

    $ git checkout -b branch-name

Additional git and GitHub resources:

Contributor checklist