From 36d29828548563e0aede3b0ec41e4581665218bc Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 10 Apr 2026 06:22:12 +0000 Subject: [PATCH 1/6] 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 2/6] 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 3/6] 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 4/6] 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 5/6] 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 6/6] 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 ```