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 work and interest in improving the TensorFlow API.
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 for the core TensorFlow repo.) All code contributors are required to sign a Contributor License Agreement (CLA).
To avoid duplicating work, please review current RFCs and contact the developers on the TensorFlow forums 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 “easy” and "good first issue" projects first; this helps the contributor become familiar with the contribution workflow, and for the core devs to become acquainted with the contributor.
good first issue
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.
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
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.
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:
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.)
Clone down the repo to your local system.
$ git clone email@example.com:your-user-name/project-name.git
Create a new branch to hold your work.
$ git checkout -b new-branch-name
Work on your new code. Write and run tests.
Commit your changes.
$ git add -a
$ git commit -m "commit message here"
Push your changes to your GitHub repo.
$ git push origin branch-name
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 accross 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 detals, see the GitHub guide on PRs.
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.
Set the upstream remote. (You only have to do this once per project, not every time.)
$ git remote add upstream firstname.lastname@example.org:tensorflow/project-repo-name
Switch to the local master branch.
$ git checkout master
Pull down the changes from upstream.
$ git pull upstream master
Push the changes to your GitHub account. (Optional, but a good practice.)
$ git push origin master
Create a new branch if you are starting new work.
$ git checkout -b branch-name
git and GitHub resources:
- Read contributing guidelines.
- Read the Code of Conduct.
- Ensure you have signed the Contributor License Agreement (CLA).
- Check if your changes are consistent with the guidelines.
- Check if your changes are consistent with the TensorFlow coding style.
- Run unit tests.