From 36d29828548563e0aede3b0ec41e4581665218bc Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 10 Apr 2026 06:22:12 +0000 Subject: [PATCH 01/15] Add more information to CONTRIBUTING.md This adds much more information about development practices and expectations. --- CONTRIBUTING.md | 259 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 214 insertions(+), 45 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d5b67e7e..9a90d9272 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,62 +1,231 @@ -# Contributing +# How to contribute -## Contributor License Agreements +Thank you for your interest in contributing to this project! We look forward to +working with you. Here are some guidelines to get you started. -We'd love to accept your patches! Before we can take them, we have to jump a -couple of legal hurdles. +## Before you begin -Please fill out either the individual or corporate Contributor License Agreement -(CLA). +### Summary -* If you are an individual writing original source code and you're sure you - own the intellectual property, then you'll need to sign an - [individual CLA](http://code.google.com/legal/individual-cla-v1.0.html). -* If you work for a company that wants to allow you to contribute your work, - then you'll need to sign a - [corporate CLA](http://code.google.com/legal/corporate-cla-v1.0.html). +* Read and sign the [Contributor License Agreement (CLA)]( + https://cla.developers.google.com/). +* Read the [code of conduct](CODE_OF_CONDUCT.md). +* Follow the [contribution process](#development-process). -Follow either of the two links above to access the appropriate CLA and -instructions for how to sign and return it. Once we receive it, we'll be able to -accept your pull requests. +### Sign our Contributor License Agreement -NOTE: Only original source code from you and other people that have signed the -CLA can be accepted into the main repository. +Contributions to this project must be accompanied by a [Contributor License +Agreement](https://cla.developers.google.com/about) (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. +If you or your current employer have already signed the Google CLA (even if it +was for a different project), you probably don't need to do it again. Visit + to see your current agreements or to sign +a new one. -## Code Reviews +Only original work from you and other people who have signed the CLA can be +incorporated into the project. By signing the Contributor License Agreement, you +agree that your contributions are an original work of authorship. -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests and the -[TensorFlow Community Guidelines](https://www.tensorflow.org/community/contribute) -for more information on contributor best practices. +### Review our community guidelines -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. +In the interest of fostering an open and welcoming environment, contributors and +maintainers pledge to make participation in our project and our community a +harassment-free experience for everyone. Our community aspires to treat everyone +equally, and to value all contributions. Please review our [code of conduct]( +CODE_OF_CONDUCT.md) for more information. -## Code Standards +## Code base conventions -We have some standards in place to ensure that incoming code is the highest -quality it can be. Before a code review can happen you should make sure that -the following tests are passing locally: +TensorFlow Quantum (TFQ) is a Python framework for quantum machine learning +(QML) implemented as an add-on to [TensorFlow](https://tensorflow.org). User +documentation for TFQ is available on the [TensorFlow Quantum documentation +site](https://tensorflow.org/quantum). The TFQ project generally follows +TensorFlow development practices, and the [TensorFlow contributors' guide]( +https://www.tensorflow.org/community/contribute) is essential reading if you +want to get involved with TFQ. -1. `./scripts/test_all.sh` passes. We use TensorFlow's testing suite for our -testing and be sure that any code you add follows the structure they have -[outlined](https://www.tensorflow.org/api_docs/python/tf/test). +### Getting oriented -2. `./scripts/lint_all.sh` passes. We use [pylint](https://www.pylint.org/) -to ensure that code has proper formatting and is lint free. +Here is a summary of the main subdirectories in the TFQ source tree: -3. `./scripts/format_check.sh` passes. We use -[yapf](https://github.com/google/yapf) along with -[clang format](https://clang.llvm.org/docs/ClangFormat.html) to ensure we have -consistent formatting everywhere. +* **benchmarks/**: Code for performance benchmarking +* **docs/**: Documentation source files +* **release/**: Scripts and configurations for building and releasing TFQ + packages +* **scripts/**: Utility scripts for running tests and doing various + development tasks +* **tensorflow_quantum/**: The core source code for TensorFlow Quantum +* **third_party/**: External dependencies and third-party integrations +* **.github/**: GitHub-specific configurations, such as continuous + integration workflows -### Adding Modules +### Coding style -If you are adding new modules, be sure to properly expose them to the user -using `__init__.py` files and update the `/scripts/import_test.py` file -to ensure that you are exposing them properly. +This project follows the [style guidelines for TensorFlow]( +https://www.tensorflow.org/community/contribute/code_style), which in turn +follows these Google style guides: +* [C++ Style Guide](https://google.github.io/styleguide/cppguide.html) +* [Python Style Guide](https://google.github.io/styleguide/pyguide.html) +* [Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) +* [Shell Style Guide](https://google.github.io/styleguide/shellguide.html) + +Software tool configurations can be found in the following files at the top +level of the source tree: + +* `.editorconfig`: basic code editor configuration +* `.pylintrc`: configuration for linting Python files using + [pylint](https://www.pylint.org/) +* `.style.yapf`: configuration for formatting Python files using [YAPF]( + https://github.com/google/yapf) +* `.yamllint.yaml`: configuration for linting YAML files using [yamllint]( + https://github.com/adrienverge/yamllint) + +All new source code files longer than 2 lines must begin with a header comment +with the copyright and license. + +### Git conventions + +Git commits should be granular. Small, focused commits have many benefits: +changes are easier to understand and evaluate (leading to faster and more +thorough PR reviews), they allow more effective use of tools like `git bisect` +for debugging, and they make managing changes easier with tools like `git +cherry-pick` and `git rebase`. + +Each commit should: + +* Represent a single, self-contained change, such as a specific bug fix or the + addition of a specific feature. + +* Not combine unrelated changes. Reverting a commit should not affect unrelated + parts of the overall code. + +* Have an easily understood, concise title written in the imperative: "Fix bug + ABC," and not "Fixed bug ABC" or "Fixes bug ABC." This convention fits well + with messages generated by commands like `git merge` and `git revert`. + +* Include a description, unless the change is exceptionally small or obvious. + +## Development process + +TensorFlow Quantum development takes place on GitHub using a GitHub-centric +workflow. + +### Check past issues + +Before you begin work, check the [GitHub Issue Tracker]( +https://github.com/tensorflow/quantum/issues?q=sort%3Aupdated-desc+is%3Aissue) +(including closed issues) if your idea or bug has been discussed before. + +Before beginning on any substantial changes, we recommend opening a new issue +on GitHub (if one doesn't already exist for the topic) and discussing your +proposed changes. This will let us give you advice on the proposed changes. + +### Repository forks + +The preferred approach to working on TFQ is to [fork]( +https://docs.github.com/articles/fork-a-repo) the repository to your GitHub +account, clone that fork to your local computing environment, and create a new +[git branch](https://docs.github.com/articles/about-branches) in the fork to do +your work. + +### Environment setup + +Follow the instructions in [docs/install.md](docs/install.md) for setting up a +development environment. After doing that, you should end up with: + +* The correct version of Bazel (6.5.0) +* A Python virtual environment +* The TFQ Python requirements installed in that Python virtual environment +* The TFQ build configured by running `./configure.sh` + +### Adding modules + +If you are adding new modules, be sure to properly expose them to the user using +`__init__.py` files and update the `scripts/import_test.py` file to ensure that +you are exposing them properly. + +### Linting and formatting + +Code should meet common style standards for Python and be free of error-prone +constructs. Use the following commands regularly to lint and reformat your code +according to project conventions: + +```shell +scripts/lint_all.sh +scripts/format_check.sh +``` + +If the format check reports formatting issues, you can correct them +automatically using + +```shell +scripts/format_all.sh +``` + +### Builds + +For relatively "quick" builds of TFQ during development, you can use the +following command: + +```shell +bazel build -c opt --cxxopt="-O3" --cxxopt="-march=native" release:build_pip_package +``` + +("Quick" here is relative: depending on the capabilities of your computer, a +build takes anywhere from a few minutes to tens of minutes.) + +### Running tests + +When new functions, classes, and files are introduced, they should also have +corresponding tests. Bug fixes also generally require new unit tests, because +the presence of bugs usually indicates insufficient test coverage. Existing +tests must continue to pass (or be updated) when changes are introduced. + +We use TensorFlow's testing suite for our testing. Make sure that any code that +you add follows the [structure outlined in the TensorFlow documentation]( +https://www.tensorflow.org/api_docs/python/tf/test). To run the TFQ test suite, +use the following command: + +```shell +scripts/test_all.sh +``` + +### Contributing code + +All submissions require review. We use GitHub's tools for [pull requests]( +https://docs.github.com/articles/about-pull-requests) for this purpose. + +#### Final checks + +Before opening a pull request and requesting a code review, you should make sure +that the following tests are passing locally: + +```shell +scripts/lint_all.sh +scripts/format_check.sh +scripts/test_all.sh +``` + +#### Draft pull requests + +When getting ready to submit your work, first create a [_draft_ pull request]( +https://help.github.com/articles/creating-a-pull-request-from-a-fork) from your +branch on GitHub to the main project repository. This will trigger continuous +integration (CI) checks and other automation on GitHub. The results will appear +on the PR page on GitHub. Monitor the CI checks on your PR; if any tests fail, +iterate on the develop-test-commit-push process until the problems are +resolved. + +#### Code review + +Once all the CI checks pass and you are ready to submit the PR for +consideration, [mark the PR as ready for review]( +https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request). + +A reviewer from the TFQ team will comment on your code and may ask for changes. +You can perform the necessary changes locally, commit them to your branch as +usual, and then push changes to your fork on GitHub following the same process +as above. When you do that, GitHub will update the code in the pull request +automatically. From 44ab5b7b0a9d33cede50f1db58f26bd72a65bd3c Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 10 Apr 2026 06:22:59 +0000 Subject: [PATCH 02/15] Improve the title of the document --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a90d9272..04faf4441 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# How to contribute +# Contributing to TensorFlow Quantum Thank you for your interest in contributing to this project! We look forward to working with you. Here are some guidelines to get you started. From 8e133804586c60946ab36f5f250d0081764e30c0 Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 10 Apr 2026 17:01:00 +0000 Subject: [PATCH 03/15] Editing and reformatting --- CONTRIBUTING.md | 171 +++++++++++++++++++++++------------------------- 1 file changed, 83 insertions(+), 88 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04faf4441..4f0021010 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,21 +7,23 @@ working with you. Here are some guidelines to get you started. ### Summary -* Read and sign the [Contributor License Agreement (CLA)]( - https://cla.developers.google.com/). -* Read the [code of conduct](CODE_OF_CONDUCT.md). -* Follow the [contribution process](#development-process). +* Read and sign the [Contributor License Agreement] +* Read the [code of conduct]. +* Follow the [development process]. + +[Contributor License Agreement]: https://cla.developers.google.com/ +[code of conduct]: ./CODE_OF_CONDUCT.md +[development process]: #development-process ### Sign our Contributor License Agreement Contributions to this project must be accompanied by a [Contributor License -Agreement](https://cla.developers.google.com/about) (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. -If you or your current employer have already signed the Google CLA (even if it -was for a different project), you probably don't need to do it again. Visit - to see your current agreements or to sign -a new one. +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. If you or your current employer have +already signed the Google CLA (even if it was for a different project), you +probably don't need to do it again. Visit +to see your current agreements or to sign a new one. Only original work from you and other people who have signed the CLA can be incorporated into the project. By signing the Contributor License Agreement, you @@ -32,39 +34,37 @@ agree that your contributions are an original work of authorship. In the interest of fostering an open and welcoming environment, contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone. Our community aspires to treat everyone -equally, and to value all contributions. Please review our [code of conduct]( -CODE_OF_CONDUCT.md) for more information. +equally, and to value all contributions. Please review our [code of conduct] for +more information. ## Code base conventions TensorFlow Quantum (TFQ) is a Python framework for quantum machine learning -(QML) implemented as an add-on to [TensorFlow](https://tensorflow.org). User -documentation for TFQ is available on the [TensorFlow Quantum documentation -site](https://tensorflow.org/quantum). The TFQ project generally follows -TensorFlow development practices, and the [TensorFlow contributors' guide]( -https://www.tensorflow.org/community/contribute) is essential reading if you -want to get involved with TFQ. +(QML) implemented as an add-on to [TensorFlow]. User documentation for TFQ is +available on the [TensorFlow Quantum documentation site]. The TFQ project +generally follows TensorFlow development practices, and the [TensorFlow +contribution guide] is essential reading if you want to get involved with TFQ. + +[TensorFlow]: https://tensorflow.org +[TensorFlow Quantum documentation site]: https://tensorflow.org/quantum +[TensorFlow contribution guide]: https://www.tensorflow.org/community/contribute ### Getting oriented Here is a summary of the main subdirectories in the TFQ source tree: -* **benchmarks/**: Code for performance benchmarking -* **docs/**: Documentation source files -* **release/**: Scripts and configurations for building and releasing TFQ - packages -* **scripts/**: Utility scripts for running tests and doing various - development tasks -* **tensorflow_quantum/**: The core source code for TensorFlow Quantum -* **third_party/**: External dependencies and third-party integrations -* **.github/**: GitHub-specific configurations, such as continuous - integration workflows +* `benchmarks/`: Code for performance benchmarking +* `docs/`: Documentation source files +* `release/`: Scripts and configurations for building TFQ releases +* `scripts/`: Utility for running tests and doing other tasks +* `tensorflow_quantum/`: The core source code for TensorFlow Quantum +* `third_party/`: External dependencies and third-party integrations +* *`github/`: GitHub-specific configurations and workflows ### Coding style -This project follows the [style guidelines for TensorFlow]( -https://www.tensorflow.org/community/contribute/code_style), which in turn -follows these Google style guides: +This project follows the [TensorFlow style], which in turn follows these Google +style guides: * [C++ Style Guide](https://google.github.io/styleguide/cppguide.html) * [Python Style Guide](https://google.github.io/styleguide/pyguide.html) @@ -75,62 +75,61 @@ Software tool configurations can be found in the following files at the top level of the source tree: * `.editorconfig`: basic code editor configuration -* `.pylintrc`: configuration for linting Python files using - [pylint](https://www.pylint.org/) -* `.style.yapf`: configuration for formatting Python files using [YAPF]( - https://github.com/google/yapf) -* `.yamllint.yaml`: configuration for linting YAML files using [yamllint]( - https://github.com/adrienverge/yamllint) +* `.pylintrc`: configuration for linting Python files using [Pylint] +* `.style.yapf`: configuration for formatting Python files using [YAPF] +* `.yamllint.yaml`: configuration for linting YAML files using [yamllint] All new source code files longer than 2 lines must begin with a header comment with the copyright and license. +[Pylint]: https://www.pylint.org/ +[YAPF]: https://github.com/google/yapf +[yamllint]: https://github.com/adrienverge/yamllint +[TensorFlow style]: ttps://www.tensorflow.org/community/contribute/code_style + ### Git conventions -Git commits should be granular. Small, focused commits have many benefits: -changes are easier to understand and evaluate (leading to faster and more -thorough PR reviews), they allow more effective use of tools like `git bisect` -for debugging, and they make managing changes easier with tools like `git -cherry-pick` and `git rebase`. +Git commits should be small and focused. Granular commits make changes easier to +understand and evaluate (leading to faster and more thorough PR reviews), allow +more effective use of tools like `git bisect` for debugging, and allow easier +management of changes with tools like `git cherry-pick` and `git rebase`. Each commit should: * Represent a single, self-contained change, such as a specific bug fix or the addition of a specific feature. -* Not combine unrelated changes. Reverting a commit should not affect unrelated - parts of the overall code. +* Not combine unrelated changes. Reverting a commit should not affect + unrelated parts of the overall code. * Have an easily understood, concise title written in the imperative: "Fix bug - ABC," and not "Fixed bug ABC" or "Fixes bug ABC." This convention fits well - with messages generated by commands like `git merge` and `git revert`. + ABC," and not "Fixed bug ABC" or "Fixes bug ABC." * Include a description, unless the change is exceptionally small or obvious. ## Development process -TensorFlow Quantum development takes place on GitHub using a GitHub-centric -workflow. +TFQ development takes place on GitHub using a GitHub-centric workflow. -### Check past issues +### Past issues -Before you begin work, check the [GitHub Issue Tracker]( -https://github.com/tensorflow/quantum/issues?q=sort%3Aupdated-desc+is%3Aissue) -(including closed issues) if your idea or bug has been discussed before. +First search the [issue tracker](https://github.com/tensorflow/quantum/issues) +to check if your idea or bug has been discussed before. -Before beginning on any substantial changes, we recommend opening a new issue -on GitHub (if one doesn't already exist for the topic) and discussing your -proposed changes. This will let us give you advice on the proposed changes. +Before beginning on any substantial changes, we recommend opening a new issue on +GitHub (if one doesn't already exist for the topic) and discussing your proposed +changes. This will let us give you advice on the proposed changes. -### Repository forks +### Repository forks and branches -The preferred approach to working on TFQ is to [fork]( -https://docs.github.com/articles/fork-a-repo) the repository to your GitHub -account, clone that fork to your local computing environment, and create a new -[git branch](https://docs.github.com/articles/about-branches) in the fork to do -your work. +The preferred approach to working on TensorFlow Quantum is to first create a +[fork](https://docs.github.com/articles/fork-a-repo) of the repository in your +GitHub account, then clone that fork to your local computing environment. Keep +your fork regularly synchronized with the upstream TFQ repository. Create a +separate [git branch](https://docs.github.com/articles/about-branches) for your +work on individual issues or topics. -### Environment setup +### Set up your environment Follow the instructions in [docs/install.md](docs/install.md) for setting up a development environment. After doing that, you should end up with: @@ -157,8 +156,7 @@ scripts/lint_all.sh scripts/format_check.sh ``` -If the format check reports formatting issues, you can correct them -automatically using +If the format check reports problems, you can correct them automatically using ```shell scripts/format_all.sh @@ -183,10 +181,9 @@ corresponding tests. Bug fixes also generally require new unit tests, because the presence of bugs usually indicates insufficient test coverage. Existing tests must continue to pass (or be updated) when changes are introduced. -We use TensorFlow's testing suite for our testing. Make sure that any code that -you add follows the [structure outlined in the TensorFlow documentation]( -https://www.tensorflow.org/api_docs/python/tf/test). To run the TFQ test suite, -use the following command: +We use TensorFlow's testing suite for our testing. Tests must follow the +[TensorFlow test guidelines](https://www.tensorflow.org/api_docs/python/tf/test) +in order to work correctly. To run the TFQ test suite, run this command: ```shell scripts/test_all.sh @@ -194,13 +191,13 @@ scripts/test_all.sh ### Contributing code -All submissions require review. We use GitHub's tools for [pull requests]( -https://docs.github.com/articles/about-pull-requests) for this purpose. +All submissions require review. We use GitHub's tools for code reviews on +[pull requests](https://docs.github.com/articles/about-pull-requests). #### Final checks -Before opening a pull request and requesting a code review, you should make sure -that the following tests are passing locally: +Before opening a pull request (PR) and requesting a code review, you should make +sure that the following tests are passing locally: ```shell scripts/lint_all.sh @@ -210,22 +207,20 @@ scripts/test_all.sh #### Draft pull requests -When getting ready to submit your work, first create a [_draft_ pull request]( -https://help.github.com/articles/creating-a-pull-request-from-a-fork) from your -branch on GitHub to the main project repository. This will trigger continuous -integration (CI) checks and other automation on GitHub. The results will appear -on the PR page on GitHub. Monitor the CI checks on your PR; if any tests fail, -iterate on the develop-test-commit-push process until the problems are -resolved. +When getting ready to submit your work, first create a _draft_ pull request from +your branch on GitHub to the main project repository. (Consult GitHub's +[docs](https://help.github.com/articles/creating-a-pull-request-from-a-fork) for +help on creating pull requests.) The pull request will trigger continuous +integration (CI) checks and other automation on GitHub. Monitor the checks; if +any tests fail, continue development and testing to resolve the problems. #### Code review Once all the CI checks pass and you are ready to submit the PR for -consideration, [mark the PR as ready for review]( -https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request). - -A reviewer from the TFQ team will comment on your code and may ask for changes. -You can perform the necessary changes locally, commit them to your branch as -usual, and then push changes to your fork on GitHub following the same process -as above. When you do that, GitHub will update the code in the pull request -automatically. +consideration, [mark the PR as ready for review]. A reviewer from the TFQ team +will comment on your code and may ask for changes. You can perform the necessary +changes locally, commit them to your branch as usual, and then push changes to +your fork on GitHub following the same process as above. When you do that, +GitHub will update the code in the pull request automatically. + +[mark the PR as ready for review]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request From a449dd2c46a85cb27478b06e95cf8453f795ae05 Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 10 Apr 2026 17:05:42 +0000 Subject: [PATCH 04/15] Minor fixes --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f0021010..cd5a99ce3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,7 +80,7 @@ level of the source tree: * `.yamllint.yaml`: configuration for linting YAML files using [yamllint] All new source code files longer than 2 lines must begin with a header comment -with the copyright and license. +with the copyright and license. We use the [Apache 2.0 license](./LICENSE). [Pylint]: https://www.pylint.org/ [YAPF]: https://github.com/google/yapf @@ -103,7 +103,7 @@ Each commit should: unrelated parts of the overall code. * Have an easily understood, concise title written in the imperative: "Fix bug - ABC," and not "Fixed bug ABC" or "Fixes bug ABC." + ABC," and not "Fixed bug ABC" or "Fixes bug ABC". * Include a description, unless the change is exceptionally small or obvious. @@ -168,7 +168,7 @@ For relatively "quick" builds of TFQ during development, you can use the following command: ```shell -bazel build -c opt --cxxopt="-O3" --cxxopt="-march=native" release:build_pip_package +bazel build -c opt --cxxopt="-O3" release:build_pip_package ``` ("Quick" here is relative: depending on the capabilities of your computer, a From ac8a058bb119c1d6ade7a9da6f834c9deb76a8fb Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 10 Apr 2026 17:33:06 +0000 Subject: [PATCH 05/15] Further improvements and fixes --- CONTRIBUTING.md | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd5a99ce3..3556b961a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,7 @@ more information. ## Code base conventions TensorFlow Quantum (TFQ) is a Python framework for quantum machine learning -(QML) implemented as an add-on to [TensorFlow]. User documentation for TFQ is +(QML) implemented as an add-on to [TensorFlow]. Documentation for TFQ is available on the [TensorFlow Quantum documentation site]. The TFQ project generally follows TensorFlow development practices, and the [TensorFlow contribution guide] is essential reading if you want to get involved with TFQ. @@ -56,10 +56,15 @@ Here is a summary of the main subdirectories in the TFQ source tree: * `benchmarks/`: Code for performance benchmarking * `docs/`: Documentation source files * `release/`: Scripts and configurations for building TFQ releases -* `scripts/`: Utility for running tests and doing other tasks +* `scripts/`: Utilities for running tests and doing other tasks * `tensorflow_quantum/`: The core source code for TensorFlow Quantum * `third_party/`: External dependencies and third-party integrations -* *`github/`: GitHub-specific configurations and workflows +* `.github/`: GitHub-specific configurations and workflows + +Some of the important files found at the top level include the following: + +* `configure.sh`: TFQ build configuration script +* `requirements.txt`: Python dependencies ### Coding style @@ -85,7 +90,7 @@ with the copyright and license. We use the [Apache 2.0 license](./LICENSE). [Pylint]: https://www.pylint.org/ [YAPF]: https://github.com/google/yapf [yamllint]: https://github.com/adrienverge/yamllint -[TensorFlow style]: ttps://www.tensorflow.org/community/contribute/code_style +[TensorFlow style]: https://www.tensorflow.org/community/contribute/code_style ### Git conventions @@ -103,7 +108,7 @@ Each commit should: unrelated parts of the overall code. * Have an easily understood, concise title written in the imperative: "Fix bug - ABC," and not "Fixed bug ABC" or "Fixes bug ABC". + ABC" and not "Fixed bug ABC" or "Fixes bug ABC". * Include a description, unless the change is exceptionally small or obvious. @@ -135,7 +140,7 @@ Follow the instructions in [docs/install.md](docs/install.md) for setting up a development environment. After doing that, you should end up with: * The correct version of Bazel (6.5.0) -* A Python virtual environment +* A Python virtual environment with a Python version between 3.10 and 3.12 * The TFQ Python requirements installed in that Python virtual environment * The TFQ build configured by running `./configure.sh` @@ -165,14 +170,16 @@ scripts/format_all.sh ### Builds For relatively "quick" builds of TFQ during development, you can use the -following command: +following command, which builds everything needed for a release and thus acts as +good indicator that changes in one part of the code do not break other parts: ```shell -bazel build -c opt --cxxopt="-O3" release:build_pip_package +bazel build release:build_pip_package ``` -("Quick" here is relative: depending on the capabilities of your computer, a -build takes anywhere from a few minutes to tens of minutes.) +(The first time you run the command above, it will take a long time, but +subsequent invocations will be much faster because Bazel is smart about what it +rebuilds.) ### Running tests @@ -183,12 +190,26 @@ tests must continue to pass (or be updated) when changes are introduced. We use TensorFlow's testing suite for our testing. Tests must follow the [TensorFlow test guidelines](https://www.tensorflow.org/api_docs/python/tf/test) -in order to work correctly. To run the TFQ test suite, run this command: +in order to work correctly. To run the full TFQ test suite, run this command: ```shell scripts/test_all.sh ``` +During development, it is often useful to run tests on just one file, which you +can do using a command of this form: + +```shell +bazel test //tensorflow_quantum/SUBDIRECTORY:FILE +``` + +where _SUBDIRECTORY_ is a subdirectory under `tensorflow_quantum/` and `FILE` is +a unit test file. Here is a full example: + +```shell +bazel test //tensorflow_quantum/python/differentiators:adjoint_test +``` + ### Contributing code All submissions require review. We use GitHub's tools for code reviews on From ef6afeae608c9514ce2c75004a36c2f5789ebaaa Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 10 Apr 2026 22:34:11 +0000 Subject: [PATCH 06/15] Correct the order off linting & formatting Format first, then lint. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3556b961a..f595a07e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -157,8 +157,8 @@ constructs. Use the following commands regularly to lint and reformat your code according to project conventions: ```shell -scripts/lint_all.sh scripts/format_check.sh +scripts/lint_all.sh ``` If the format check reports problems, you can correct them automatically using @@ -221,8 +221,8 @@ Before opening a pull request (PR) and requesting a code review, you should make sure that the following tests are passing locally: ```shell -scripts/lint_all.sh scripts/format_check.sh +scripts/lint_all.sh scripts/test_all.sh ``` From 16508e376766c6baf9b710cfeeb299a102766957 Mon Sep 17 00:00:00 2001 From: mhucka Date: Wed, 15 Apr 2026 02:20:25 +0000 Subject: [PATCH 07/15] Added more information --- CONTRIBUTING.md | 61 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f595a07e9..79c180e3a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,8 +18,8 @@ working with you. Here are some guidelines to get you started. ### Sign our 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 +Agreement] (CLA). You or your employer retain the copyright to your +contribution; the CLA simply gives us permission to use and redistribute your contributions as part of the project. If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again. Visit @@ -63,6 +63,7 @@ Here is a summary of the main subdirectories in the TFQ source tree: Some of the important files found at the top level include the following: +* `README.md`: General introduction to the project * `configure.sh`: TFQ build configuration script * `requirements.txt`: Python dependencies @@ -80,24 +81,26 @@ Software tool configurations can be found in the following files at the top level of the source tree: * `.editorconfig`: basic code editor configuration -* `.pylintrc`: configuration for linting Python files using [Pylint] -* `.style.yapf`: configuration for formatting Python files using [YAPF] -* `.yamllint.yaml`: configuration for linting YAML files using [yamllint] +* `.markdownlintrc`: linting Markdown files using [markdownlint-cli] +* `.pylintrc`: linting Python files using [Pylint] +* `.style.yapf`: formatting Python files using [YAPF] +* `.yamllint.yaml`: linting YAML files using [yamllint] -All new source code files longer than 2 lines must begin with a header comment +All source code files longer than a few lines must begin with a header comment with the copyright and license. We use the [Apache 2.0 license](./LICENSE). -[Pylint]: https://www.pylint.org/ +[markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli +[Pylint]: https://www.pylint.org [YAPF]: https://github.com/google/yapf [yamllint]: https://github.com/adrienverge/yamllint [TensorFlow style]: https://www.tensorflow.org/community/contribute/code_style ### Git conventions -Git commits should be small and focused. Granular commits make changes easier to -understand and evaluate (leading to faster and more thorough PR reviews), allow -more effective use of tools like `git bisect` for debugging, and allow easier -management of changes with tools like `git cherry-pick` and `git rebase`. +Git commits should be small and focused. Granular commits make changes easier +and faster to understand and evaluate, allow more effective use of tools like +`git bisect` for debugging, and allow easier management of changes with tools +like `git cherry-pick` and `git rebase`. Each commit should: @@ -118,12 +121,12 @@ TFQ development takes place on GitHub using a GitHub-centric workflow. ### Past issues -First search the [issue tracker](https://github.com/tensorflow/quantum/issues) +First, search the [issue tracker](https://github.com/tensorflow/quantum/issues) to check if your idea or bug has been discussed before. Before beginning on any substantial changes, we recommend opening a new issue on -GitHub (if one doesn't already exist for the topic) and discussing your proposed -changes. This will let us give you advice on the proposed changes. +GitHub (if one doesn't already exist for the topic) to describe your proposed +changes. This will allow the maintainers to provide feedback. ### Repository forks and branches @@ -134,7 +137,7 @@ your fork regularly synchronized with the upstream TFQ repository. Create a separate [git branch](https://docs.github.com/articles/about-branches) for your work on individual issues or topics. -### Set up your environment +### Environment setup Follow the instructions in [docs/install.md](docs/install.md) for setting up a development environment. After doing that, you should end up with: @@ -167,11 +170,11 @@ If the format check reports problems, you can correct them automatically using scripts/format_all.sh ``` -### Builds +### Building TFQ For relatively "quick" builds of TFQ during development, you can use the following command, which builds everything needed for a release and thus acts as -good indicator that changes in one part of the code do not break other parts: +a good indicator that changes in one part of the code do not break other parts: ```shell bazel build release:build_pip_package @@ -230,11 +233,20 @@ scripts/test_all.sh When getting ready to submit your work, first create a _draft_ pull request from your branch on GitHub to the main project repository. (Consult GitHub's -[docs](https://help.github.com/articles/creating-a-pull-request-from-a-fork) for -help on creating pull requests.) The pull request will trigger continuous +[docs](https://docs.github.com/articles/creating-a-pull-request-from-a-fork) for +help on creating draft pull requests.) The pull request will trigger continuous integration (CI) checks and other automation on GitHub. Monitor the checks; if any tests fail, continue development and testing to resolve the problems. +#### Continuous integration (CI) + +Every time a PR is opened or updated on GitHub, automated workflows run checks +on the files in the PR. These workflows run the format, lint, and test scripts +mentioned above; they also do additional verification, such as checking that all +authors on the PR have signed the [Contributor License Agreement]. The outcomes +of the checks (success, or failures and error messages) will be shown on the +pull request page on GitHub. + #### Code review Once all the CI checks pass and you are ready to submit the PR for @@ -245,3 +257,14 @@ your fork on GitHub following the same process as above. When you do that, GitHub will update the code in the pull request automatically. [mark the PR as ready for review]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request + +#### Closure + +Most of the time, after changes are discussed and implemented during the code +review, the project maintainers will eventually merge the PR into the TensorFlow +Quantum code base. At that point, the work on the PR will be completed. + +On rare occasions, the maintainers may decline to merge the PR and recommend a +different course of action. This will usually be indicated early on – +nobody wants to waste time and effort iterating on something that will be +rejected! From a36cc40eb17f0a0b390ca04227411c0de703fe77 Mon Sep 17 00:00:00 2001 From: mhucka Date: Wed, 15 Apr 2026 02:48:58 +0000 Subject: [PATCH 08/15] Leave off final paragraph It's a bit too negative. --- CONTRIBUTING.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 79c180e3a..c3dd607f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -263,8 +263,3 @@ GitHub will update the code in the pull request automatically. Most of the time, after changes are discussed and implemented during the code review, the project maintainers will eventually merge the PR into the TensorFlow Quantum code base. At that point, the work on the PR will be completed. - -On rare occasions, the maintainers may decline to merge the PR and recommend a -different course of action. This will usually be indicated early on – -nobody wants to waste time and effort iterating on something that will be -rejected! From 2cb43bf1560b413329745f42c057d3ca6eadc9cc Mon Sep 17 00:00:00 2001 From: mhucka Date: Thu, 16 Apr 2026 22:08:03 +0000 Subject: [PATCH 09/15] Add more details about what we want in PRs Based on feedback from Pablo, I added some text to request more information in people's PRs. --- CONTRIBUTING.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3dd607f4..60f26f4f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -234,9 +234,18 @@ scripts/test_all.sh When getting ready to submit your work, first create a _draft_ pull request from your branch on GitHub to the main project repository. (Consult GitHub's [docs](https://docs.github.com/articles/creating-a-pull-request-from-a-fork) for -help on creating draft pull requests.) The pull request will trigger continuous -integration (CI) checks and other automation on GitHub. Monitor the checks; if -any tests fail, continue development and testing to resolve the problems. +help on creating draft pull requests.) + +When writing the PR title and description, please include the following: + +* A concise but descriptive title +* A summary of what the PR is about +* How you tested and validated the changes +* Any important notes, such as assumptions, edge cases, etc. + +The pull request will trigger continuous integration (CI) checks and other +automation on GitHub. Monitor the checks; if any tests fail, continue +development and testing to resolve the problems. #### Continuous integration (CI) @@ -260,6 +269,6 @@ GitHub will update the code in the pull request automatically. #### Closure -Most of the time, after changes are discussed and implemented during the code -review, the project maintainers will eventually merge the PR into the TensorFlow -Quantum code base. At that point, the work on the PR will be completed. +After code review is finished, requested changes (if any) are made, and the PR +is accepted, the project maintainers will merge the PR into the code base. At +that point, the work on the PR will be completed. From 97787ba8cf93f1fc53ac072aa317b0edef06ee96 Mon Sep 17 00:00:00 2001 From: mhucka Date: Thu, 16 Apr 2026 22:28:28 +0000 Subject: [PATCH 10/15] Take out markdownlint bits for now Having trouble figuring out how to make markdownlint-cli easily installable for people. --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60f26f4f8..5eb09ef5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,7 +81,6 @@ Software tool configurations can be found in the following files at the top level of the source tree: * `.editorconfig`: basic code editor configuration -* `.markdownlintrc`: linting Markdown files using [markdownlint-cli] * `.pylintrc`: linting Python files using [Pylint] * `.style.yapf`: formatting Python files using [YAPF] * `.yamllint.yaml`: linting YAML files using [yamllint] @@ -89,7 +88,6 @@ level of the source tree: All source code files longer than a few lines must begin with a header comment with the copyright and license. We use the [Apache 2.0 license](./LICENSE). -[markdownlint-cli]: https://github.com/igorshubovych/markdownlint-cli [Pylint]: https://www.pylint.org [YAPF]: https://github.com/google/yapf [yamllint]: https://github.com/adrienverge/yamllint From a88b392bf137a3eef15c91fd02a5e777bcfb1750 Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 17 Apr 2026 19:43:56 +0000 Subject: [PATCH 11/15] Fix typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5eb09ef5e..d567cfb0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -268,5 +268,5 @@ GitHub will update the code in the pull request automatically. #### Closure After code review is finished, requested changes (if any) are made, and the PR -is accepted, the project maintainers will merge the PR into the code base. At +is approved, the project maintainers will merge the PR into the code base. At that point, the work on the PR will be completed. From e82c572d51e9dafa29d9b75c9d249cd4a0a7cf51 Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 17 Apr 2026 20:28:12 +0000 Subject: [PATCH 12/15] Add mention of `.clang-format` file --- CONTRIBUTING.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d567cfb0a..e88b87fcc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,6 +80,7 @@ style guides: Software tool configurations can be found in the following files at the top level of the source tree: +* `.clang-format`: formatting C++ files using [clang-format] * `.editorconfig`: basic code editor configuration * `.pylintrc`: linting Python files using [Pylint] * `.style.yapf`: formatting Python files using [YAPF] @@ -88,10 +89,11 @@ level of the source tree: All source code files longer than a few lines must begin with a header comment with the copyright and license. We use the [Apache 2.0 license](./LICENSE). +[clang-format]: https://releases.llvm.org/18.1.6/tools/clang/docs/ClangFormat.html [Pylint]: https://www.pylint.org -[YAPF]: https://github.com/google/yapf -[yamllint]: https://github.com/adrienverge/yamllint [TensorFlow style]: https://www.tensorflow.org/community/contribute/code_style +[yamllint]: https://github.com/adrienverge/yamllint +[YAPF]: https://github.com/google/yapf ### Git conventions From 3b2d3d0c31e98b08fddbe88e2d64eb465aa64a05 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Fri, 17 Apr 2026 13:47:02 -0700 Subject: [PATCH 13/15] Update CONTRIBUTING.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e88b87fcc..32e38bc39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ working with you. Here are some guidelines to get you started. * Follow the [development process]. [Contributor License Agreement]: https://cla.developers.google.com/ -[code of conduct]: ./CODE_OF_CONDUCT.md +[code of conduct]: CODE_OF_CONDUCT.md [development process]: #development-process ### Sign our Contributor License Agreement From d1b37a2598099b48dbf8d9142d18b3c7c3b22bb6 Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Fri, 17 Apr 2026 13:48:17 -0700 Subject: [PATCH 14/15] Update CONTRIBUTING.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32e38bc39..13dbf31c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -203,7 +203,7 @@ During development, it is often useful to run tests on just one file, which you can do using a command of this form: ```shell -bazel test //tensorflow_quantum/SUBDIRECTORY:FILE +bazel test //tensorflow_quantum/SUBDIRECTORY:TARGET ``` where _SUBDIRECTORY_ is a subdirectory under `tensorflow_quantum/` and `FILE` is From ff38bdf276ce62d1a5f748fe67b911ba75479f3f Mon Sep 17 00:00:00 2001 From: Michael Hucka Date: Fri, 17 Apr 2026 13:49:49 -0700 Subject: [PATCH 15/15] Additional edits after GCA's review --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 13dbf31c3..528fc8959 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -206,8 +206,8 @@ can do using a command of this form: bazel test //tensorflow_quantum/SUBDIRECTORY:TARGET ``` -where _SUBDIRECTORY_ is a subdirectory under `tensorflow_quantum/` and `FILE` is -a unit test file. Here is a full example: +where _SUBDIRECTORY_ is a subdirectory under `tensorflow_quantum/` and `TARGET` +is a test. Here is a full example: ```shell bazel test //tensorflow_quantum/python/differentiators:adjoint_test