From 21db4f0b68e04ae94e48e7092d85601d21adcbae Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:14:04 +0000 Subject: [PATCH 01/19] Expand CONTRIBUTING.md with more info This adds much more information about this project's conventions, development process, and contributor workflow. --- CONTRIBUTING.md | 395 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 353 insertions(+), 42 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d5b67e7e..67aaf6619 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,62 +1,373 @@ -# Contributing +# Guidelines for contributing to this project -## Contributor License Agreements +Welcome, and thank you for your interest in contributing to our project! We're +excited to work with you. To ensure a smooth and effective collaboration, please +follow these guidelines. -We'd love to accept your patches! Before we can take them, we have to jump a -couple of legal hurdles. +## Getting Started -Please fill out either the individual or corporate Contributor License Agreement -(CLA). +Before you write any code, please complete the following steps. This will set +you up for success and ensure your contributions can be merged smoothly. -* 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). +* Review our [community guidelines](#learn-our-community-guidelines) to + understand our commitment to a welcoming and harassment-free environment. -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 the [Contributor License Agreement (CLA)](#cla) to grant us permission + to use your work. -NOTE: Only original source code from you and other people that have signed the -CLA can be accepted into the main repository. +* Set up a [GitHub account](https://github.com) if you do not already have + one. All contributions in this project (bug fixes, new development, + documentation, etc.) follow a GitHub-centered workflow. -## Code Reviews +* Learn how to find [opportunities for contributions](#opportunities). -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. +* Understand our [development process](#development-process) and [contribution + workflow](#contribution-workflow). -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. +### Learn our community guidelines -## Code Standards +We strive to create an open and welcoming community where everyone is treated +with respect. All contributors and maintainers pledge to make participation a +harassment-free experience for everyone, regardless of background or experience. -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: +Our key principles include: -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). +* Using welcoming and inclusive language. +* Being respectful of different viewpoints and experiences. +* Gracefully accepting constructive criticism. +* Focusing on what is best for the project and the community. -2. `./scripts/lint_all.sh` passes. We use [pylint](https://www.pylint.org/) -to ensure that code has proper formatting and is lint free. +Please read our full [Code of Conduct](CODE_OF_CONDUCT.md) for more details. -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. +### Sign the Contributor License Agreement -### Adding Modules +All contributions to this project must be accompanied by a signed [Contributor +License Agreement (CLA)](https://cla.developers.google.com/). + +* _What it does_: The CLA gives us permission to use and redistribute your + contributions as part of the project. You (or your employer) retain full + copyright to your work. + +* _How to sign_: Visit + [cla.developers.google.com](https://cla.developers.google.com/) to sign the + agreement or check your status. You typically only need to sign a Google CLA + once, and it covers contributions to all of Google's open-source projects. + +* _Originality_: By signing the CLA, you confirm that your contributions are + original works of authorship. Although coding assistance tools are + permitted, the final contribution must be your own creation. + +Only original works from you and other people who signed the CLA can be merged +into this project. + +### Finding opportunities to make contributions + +The best way to get started is by tackling an existing issue. + +1. Navigate to the [Issues tab](https://github.com/tensorflow/quantum/issues) + on GitHub. + +2. Filter the issues list for those labeled ["good first + issue"](https://github.com/tensorflow/quantum/labels/good%20first%20issue). + These are specifically chosen as good entry points for new contributors. + +3. Once you pick an issue, leave a comment to let others know you are working + on it. This helps prevent duplicated effort. + +## Development process + +This section describes the development process: + +* Preliminary software requirements +* How to set up a local development environment +* How to build TensorFlow Quantum locally +* How to run tests locally +* How to add new modules to TensorFlow Quantum + +### Preliminary software requirements + +Install the tools described in the [install TensorFlow Quantum]( +docs/install.md) guide's section on how to build from source. The required tools +include Python version 3.10 or greater, as well as [git](https://git-scm.com/), +[pip](https://pip.pypa.io/en/stable/), a working Clang or GCC compiler toolchain +that supports C++ 17, and [Bazel](https://bazel.build/) version 6.5.0. + +### Setting up a local development environment + +1. Fork the TFQ repository to your account on GitHub. (Go to the TFQ repo page + on GitHub and use the Fork button.) For more information on forks, consult + [GitHub's guide](https://help.github.com/articles/fork-a-repo/). + +2. Clone your fork to somewhere on your computer. In the following command, + substitute your GitHub account name in place of _YOURACCOUNT_: + + ```shell + git clone git@github.com:YOURACCOUNT/quantum.git + cd quantum + ``` + +3. Set up a Python virtual environment. Here is an example of doing that with + Python's built-in [venv](https://docs.python.org/3/library/venv.html), but + you can use other methods and tools if you are more comfortable with them: + + ```shell + python3 -m venv quantum_env + source quantum_env/bin/activate + ``` + +4. Install the TFQ Python requirements into the virtual environment: + + ```shell + pip install -r requirements.txt + ``` + +### Building TensorFlow Quantum from source + +Once the TFQ dependencies have been installed as described in the previous +section, you should be able to build TFQ with these steps: + +1. Run the configuration script + + ```shell + ./configure.sh + ``` + +2. Build a pip package for TFQ: + + ```shell + bazel build -c opt release:build_pip_package + bazel-bin/release/build_pip_package /tmp/tfquantum/ + ``` + +3. The previous step will write a file with a name ending in `.whl` into the + directory `/tmp/tfquantum/`. Install this package file into your Python + virtual environment: + + ```shell + # Find out the name of the Python package (wheel) file: + ls -l /tmp/tfquantum/ + # Once you know the file name, install it: + pip install /tmp/tfquantum/NAME-OF-FILE.whl + ``` + +4. Run the TFQ tests: + + ```shell + bazel test -c opt --test_output=errors //tensorflow_quantum/... + ``` + +More options (such as building with optimization turned on) and other ways of +installing and building TensorFlow Quantum can be found in the [Build TensorFlow +Quantum from source](docs/install.md) section of the TFQ installation guide. + +### Running tests locally + +While working on changes, and especially before doing git commits, use the +following scripts to check that TensorFlow Quantum continues to run correctly +and code conforms to this project's [coding conventions](#coding-conventions): + +1. `./scripts/test_all.sh`. We use TensorFlow's testing suite for our + testing; be sure to follow the structure they have + [outlined](https://www.tensorflow.org/api_docs/python/tf/test). + +2. `./scripts/lint_all.sh`. We use [pylint](https://www.pylint.org/) to + ensure that code has proper formatting and is lint free. + +3. `./scripts/format_check.sh`. 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. + +4. `./scripts/format_ipynb.sh`. We use [`nbformat`]( + https://pypi.org/project/nbformat/) to ensure the Jupyter notebooks have + consistent style. + +5. `./scripts/format_all.sh`. This script runs the formatters (`yapf`, + `clang-format`, etc.) and automatically applies any recommended changes. + +You can also run the linters and formatters on individual files and +subdirectories when you don't need to check everything. Configuration files for +these programs are located at the top level of the TensorFlow Quantum +repository. (Also see the [section on configuration](#dot-files) below.) + +* For C++ code: + + * Run `clang-format --dry-run /path/to/file` to check the format of + the C++ file _/path/to/file_. + +* For Python code: + + * Run `pylint /path/to/file` to check _/path/to/file_ for lint. + * Run `yapf -d /path/to/file` to check the format of the file. + +### Adding new 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. +## Coding conventions + +### Coding Style + +TensorFlow Quantum follows the [TensorFlow code +style](https://www.tensorflow.org/community/contribute/code_style). Briefly: + +* For Python, we follow the [PEP 8 Python style + guide](https://www.python.org/dev/peps/pep-0008/), and the [Google Python + Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md), + except that TensorFlow uses 2 spaces instead of 4. + +* For C++ code and Protobuf definitions, we follow the [Google C++ Style + Guide](https://google.github.io/styleguide/cppguide.html) and [TensorFlow + specific style + details](https://github.com/tensorflow/community/blob/master/governance/cpp-style.md). + +* For shell scripts, we follow the [Google Shell Style Guide]( + https://google.github.io/styleguide/shellguide.html). + +* For Markdown files, we follow the [Google Markdown Style Guide]( + https://google.github.io/styleguide/docguide/style.html). + +### Editor, linter, and format checker configurations + +Configuration files for a number of programs we use can be found at the top +level of the TensorFlow Quantum repository. + +* [`.clang-format`](.clang-format) for linting and formatting C++ code and + Protobufs. + +* [`.editorconfig`](.editorconfig) for basic code editor configuration + (e.g., indentation and line length) specified using the + [EditorConfig](https://editorconfig.org/) format. + +* [`.pylintrc`](.pylintrc) for linting Python code. + +* [`.style.yapf`](.style.yapf) for reformatting Python code. + +* [`.yamllint.yaml`](.yamllint.yaml) for linting YAML files. + +### Comment conventions + +Every source file must begin with a header comment containing a copyright +statement and license. License headers are necessary in Python, C++, Bash/shell, +and other programming language files. + +For other kinds of comments, follow these guidelines: + +* _Write clear and concise comments_: Comments should explain the "why", not + the "what". The comments should explain the intent, trade-offs, and + reasoning behind the implementation. + +* _Comment sparingly_: Well-written code should be self-documenting where + possible. It's not necessary to add comments for code fragments that can + reasonably be assumed to be self-explanatory. + +* _Use complete sentences_: Start comments with a capital letter, use + proper punctuation and correct grammar. + +### Git commit do's and don't's + +We strive to follow the principles of granular commits. Making smaller, focused +commits has many benefits: changes are easier for reviewers 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`. + +A commit should: + +* Represent a single, self-contained change, such as a specific bug fix or + addition of a specific feature. It should not combine unrelated changes, + and reverting it 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. + +A commit should not: + +* Be half-done. If you‘re tempted to commit just because you need a clean + working copy (to check out a branch, pull in changes, etc.) consider using + [`git stash`](https://git-scm.com/docs/git-stash) instead. + +* Be untested. + +## Contribution workflow + +All contributions, for both code and documentation, follow the GitHub +[fork-and-pull model](https://en.wikipedia.org/wiki/Fork_and_pull_model). + +### Open an issue or comment on an existing one + +Before you begin work, check the [GitHub Issue +Tracker](https://github.com/tensorflow/quantum/issues) (including closed issues) +to see if your idea or bug has been discussed before. + +* _For existing open issues_: If you find an unassigned issue you'd like to + work on, leave a comment to claim it. + +* _For new ideas_: If your idea isn't covered by an existing issue, please + **open a new issue to discuss your proposed changes before starting work**. + This ensures we agree on the approach before you invest more time. + +### Develop your changes + +Once an issue is assigned to you, follow these steps. (This assumes you have +already forked the repo and [set up your development environment](#dev-env).) + +1. Sync your fork. Keep your fork's `master` branch up-to-date with the main + project. + + ```shell + # Add the main repo as an "upstream" remote (only needs to be done once). + git remote add upstream https://github.com/tensorflow/quantum.git + + # Fetch the latest changes and update your local master. + git checkout master + git pull upstream master + git push origin master + ``` + +2. Create a new [git branch](https://docs.github.com/articles/about-branches) + in your local clone of the TFQ git repository to do your work: + + ```shell + git checkout -b SOME-BRANCH-NAME + ``` + +3. Make your changes. Remember to write and run tests for your changes. Commit + changes often. Write small, focused commits with clear messages. + + ```shell + git add -A + git commit + ``` + +### Submit your changes for review + +1. Once you are done with a particular piece of work, push your changes to your + fork on GitHub: + + ```shell + git push origin + ``` + +2. Open a [**draft** pull request (PR)]( + https://help.github.com/articles/creating-a-pull-request-from-a-fork) + on GitHub. This will trigger continuous integration (CI) checks and other + automation. The results will appear on the PR page on GitHub. + +3. Iterate on feedback. + + * Monitor the CI checks on your PR. If any tests fail, iterate on the + develop-test-commit-push process until the problems are resolved. + + * Once all the 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). + + * Maintainers and other contributors will review your PR. Participate in + the discussion and address any comments or requested changes by pushing + additional commits. From 4cce7df73d74c13f8232e025e4b3e414f62c2c25 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:15:05 +0000 Subject: [PATCH 02/19] Update `.editorconfig` with a couple of missing items --- .editorconfig | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/.editorconfig b/.editorconfig index f93e4abe0..2a7beb6e5 100644 --- a/.editorconfig +++ b/.editorconfig @@ -12,21 +12,13 @@ # See the License for the specific language governing permissions and # limitations under the License. -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -# Common editor configurations for this project. -# -# EditorConfig is a file format for specifying some common style parameters. -# Many IDEs & editors read .editorconfig files, either natively or via plugins. -# We mostly follow Google's style guides (https://google.github.io/styleguide/) -# with only a few deviations for line length and indentation in some files. -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - root = true -# IMPORTANT: some of the other config files (.markdownlintrc, .jsonlintrc.yaml, -# etc.) also have settings for indent and line length. When making changes to -# this file, make sure to update the other files to match. +# We follow the TensorFlow coding style +# https://www.tensorflow.org/community/contribute/code_style +# IMPORTANT: some of the other config files (.clang-format, etc.) also have +# the same settings and need to be updated if changes are made to this file. [*] charset = utf-8 indent_style = space @@ -35,7 +27,7 @@ spelling_language = en-US trim_trailing_whitespace = true max_line_length = 80 -[{BUILD,*.BUILD,*.bzl,*.bazel,.bazelrc}] +[{BUILD,*.BUILD,*.bzl,*.bazel,.bazelrc,WORKSPACE}] indent_size = 4 [{*.cc,*.h}] @@ -48,7 +40,7 @@ indent_size = 2 indent_size = 4 [*.sh] -indent_size = 4 +indent_size = 2 -[*.yml,*.yaml] +[{*.yaml,*.yml,*.cff}] indent_size = 2 From d776d98cb796d77553e495887b9a17284e24d0a2 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:15:32 +0000 Subject: [PATCH 03/19] Add `.clang-format` This sets the default style (to Google style), so that `clang-format` can be invoked with the style argument. --- .clang-format | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .clang-format diff --git a/.clang-format b/.clang-format new file mode 100644 index 000000000..ba167ed48 --- /dev/null +++ b/.clang-format @@ -0,0 +1,19 @@ +# Copyright 2025 The TensorFlow Quantum Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Summary: configure clang-format for this project's style guidelines. +# This should be kept in sync with TensorFlow's .clang-format. + +BasedOnStyle: Google +DerivePointerAlignment: false From e34e23b441e5dca353e4c3d9480f9a665f5b9ab5 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:16:05 +0000 Subject: [PATCH 04/19] Add `.style.yapf` This sets the default style (to Google style), so that `yapf` can be invoked with the style argument. --- .style.yapf | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .style.yapf diff --git a/.style.yapf b/.style.yapf new file mode 100644 index 000000000..f139631b4 --- /dev/null +++ b/.style.yapf @@ -0,0 +1,18 @@ +# Copyright 2025 The TensorFlow Quantum Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Summary: configure yapf (https://github.com/google/yapf) for this project. + +[style] +based_on_style = google From e53ec774176b2bf59aad014994f1a20762e0c757 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:18:38 +0000 Subject: [PATCH 05/19] Add `.gitattributes` The content here is currently all about adjusting GitHub's file type statistics. (IMHO it's weird that GitHub doesn't list Markdown files.) --- .gitattributes | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..6f441a4a1 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,23 @@ +# Copyright 2025 The TensorFlow Quantum Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Include Markdown files in GitHub's file statistics for this repo. +*.md linguist-detectable + +# Exclude config files from GitHub's file statistics. Most are YAML files and +# Linguist already treats .yaml files as data, so only add some exceptions. +.clang-format linguist-documentation +.editorconfig linguist-documentation +.markdownlintrc linguist-documentation +.shfmt linguist-documentation From 2786c981f87d8d0a023072562d2347956fa16083 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:18:55 +0000 Subject: [PATCH 06/19] Add a CoC file --- CODE_OF_CONDUCT.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 CODE_OF_CONDUCT.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..34ac21b4b --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,91 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of +experience, education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, +offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +This Code of Conduct also applies outside the project spaces when the Project +Stewards have a reasonable belief that an individual's behavior may have a +negative impact on the project or its community. + +## Conflict Resolution + +We do not believe that all conflict is bad; healthy debate and disagreement +often yield positive results. However, it is never okay to be disrespectful or +to engage in behavior that violates the project’s Code of Conduct. + +If you see someone violating the Code of Conduct, you are encouraged to address +the behavior directly with those involved. Many issues can be resolved quickly +and easily, and this gives people more control over the outcome of their +dispute. If you are unable to resolve the matter for any reason, or if the +behavior is threatening or harassing, report it. We are dedicated to providing +an environment where participants feel welcome and safe. + +Reports should be directed to quantumai-oss-maintainers@googlegroups.com, +the project stewards at Google Quantum AI. They will then work with a committee +consisting of representatives from the Open Source Programs Office and the +Google Open Source Strategy team. If for any reason you are uncomfortable +reaching out to the Project Stewards, please email opensource@google.com. + +We will investigate every complaint, but you may not receive a direct response. +We will use our discretion in determining when and how to follow up on reported +incidents, which may range from not taking action to permanent expulsion from +the project and project-sponsored spaces. We will notify the accused of the +report and provide them an opportunity to discuss it before any action is taken. +The identity of the reporter will be omitted from the details of the report +supplied to the accused. In potentially harmful situations, such as ongoing +harassment or threats to anyone's safety, we may take action without notice. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 1.4, +available at +https://www.contributor-covenant.org/version/1/4/code-of-conduct.html From 92585c6d6bbb6bc3a273fc53bc8f81f19b841498 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:19:07 +0000 Subject: [PATCH 07/19] Add the standard `SUPPORT.md` file --- SUPPORT.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 SUPPORT.md diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 000000000..b21b8718a --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,21 @@ +# Support + +Thank you for your interest in this project! If you are experiencing problems +or have questions, the following are some suggestions for how to get help. + +> [!NOTE] +> Before participating in our community, please read our [code of +> conduct](CODE_OF_CONDUCT.md). By interacting with this repository, +> organization, or community, you agree to abide by its terms. + +## Report an issue or request a feature + +To report an issue or request a feature, please first search this project's +issue tracker on GitHub to check if there is already an open issue identical or +similar to your bug report/feature request. If there is none, go ahead and file +a new issue in the issue tracker. + +## Contact the maintainers + +For any questions or concerns not addressed here, please email +quantum-oss-maintainers@google.com. From 3880cf02f494b7793889af6a5eb72e428175529f Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:28:09 +0000 Subject: [PATCH 08/19] Follow the existing header file style in TFQ --- .clang-format | 1 + .editorconfig | 1 + .gitattributes | 1 + .pylintrc | 15 +++++++++++++++ .style.yapf | 1 + .yamllint.yaml | 1 + 6 files changed, 20 insertions(+) diff --git a/.clang-format b/.clang-format index ba167ed48..b164c4fcf 100644 --- a/.clang-format +++ b/.clang-format @@ -11,6 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +# ============================================================================ # Summary: configure clang-format for this project's style guidelines. # This should be kept in sync with TensorFlow's .clang-format. diff --git a/.editorconfig b/.editorconfig index 2a7beb6e5..bbcf3e296 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,6 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +# ============================================================================ root = true diff --git a/.gitattributes b/.gitattributes index 6f441a4a1..bbe425f1b 100644 --- a/.gitattributes +++ b/.gitattributes @@ -11,6 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +# ============================================================================ # Include Markdown files in GitHub's file statistics for this repo. *.md linguist-detectable diff --git a/.pylintrc b/.pylintrc index 387e84237..780ab2c9f 100644 --- a/.pylintrc +++ b/.pylintrc @@ -1,3 +1,18 @@ +# Copyright 2020 The TensorFlow Probability Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ============================================================================ + # Summary: TFQ config file for Pylint versions 3.0 and above. # See https://pylint.readthedocs.io/ for info about options available. diff --git a/.style.yapf b/.style.yapf index f139631b4..b2ead2e19 100644 --- a/.style.yapf +++ b/.style.yapf @@ -11,6 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +# ============================================================================ # Summary: configure yapf (https://github.com/google/yapf) for this project. diff --git a/.yamllint.yaml b/.yamllint.yaml index 64b39a528..dfe3b57a1 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -11,6 +11,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +# ============================================================================ # Summary: yamllint configuration for TensorFlow Quantum. # See https://yamllint.readthedocs.io/ for info about configuration options. From 0da65150b8cc556bd76930d2d09a5a43c595c591 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:30:20 +0000 Subject: [PATCH 09/19] Add `.github/actionlint.yaml` This configures the linter program `actionlint` for this project. It helps to have this when making changes to the GitHub Actions workflows. --- .github/actionlint.yaml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 .github/actionlint.yaml diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml new file mode 100644 index 000000000..def2afdb1 --- /dev/null +++ b/.github/actionlint.yaml @@ -0,0 +1,26 @@ +# Copyright 2020 The TensorFlow Probability Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# ============================================================================ + +# Summary: configure actionlint (https://github.com/rhysd/actionlint) to +# recognize action runner names/labels that we use. + +self-hosted-runner: + labels: + # Google self-hosted runners defined in TensorFlow org. + - linux-x86-n2-32 + + # New from GitHub (late 2025) but currently not known by actionlint. + # https://docs.github.com/en/actions/reference/runners/github-hosted-runners + - ubuntu-slim From 7cd769dbbdb7f0f22e9a72659e09f58c91785f42 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 00:47:08 +0000 Subject: [PATCH 10/19] Add more GitHub problem matchers These help improve visibility of errors in CI. --- .github/problem-matchers/README.md | 25 +++++++++++++++++++++++-- .github/problem-matchers/gcc.json | 17 +++++++++++++++++ .github/problem-matchers/pytest.json | 16 ++++++++++++++++ .github/problem-matchers/yapf.json | 22 ++++++++++++++++++++++ 4 files changed, 78 insertions(+), 2 deletions(-) create mode 100644 .github/problem-matchers/gcc.json create mode 100644 .github/problem-matchers/pytest.json create mode 100644 .github/problem-matchers/yapf.json diff --git a/.github/problem-matchers/README.md b/.github/problem-matchers/README.md index 60ede5cbb..53068eb9d 100644 --- a/.github/problem-matchers/README.md +++ b/.github/problem-matchers/README.md @@ -6,5 +6,26 @@ This directory contains Problem Matchers used by the GitHub Actions workflows in The following problem matcher JSON files found in this directory were copied from the [Home Assistant](https://github.com/home-assistant/core) project on GitHub. The Home Assistant project is licensed under the Apache 2.0 open-source license. The version of the files at the time they were copied was 2025.1.2. -- [`pylint.json`](https://github.com/home-assistant/core/blob/dev/.github/workflows/matchers/pylint.json) -- [`yamllint.json`](https://github.com/home-assistant/core/blob/dev/.github/workflows/matchers/yamllint.json) +* [`pylint.json`](https://github.com/home-assistant/core/blob/dev/.github/workflows/matchers/pylint.json) +* [`yamllint.json`](https://github.com/home-assistant/core/blob/dev/.github/workflows/matchers/yamllint.json) + +The Pytest problem matcher originally came from the +[gh-problem-matcher-wrap](https://github.com/liskin/gh-problem-matcher-wrap/tree/master/problem-matchers) +repository (copied 2025-03-04, version 3.0.0), and was subsequently modified by +Michael Hucka. The original JSON file is Copyright © 2020 Tomáš Janoušek and +made available under the terms of the MIT license. + +* [`pytest.json`](https://github.com/liskin/gh-problem-matcher-wrap/blob/master/problem-matchers/pytest.json) + +The following problem matcher for gcc came from the [Microsoft +vscode-cpptools](https://github.com/microsoft/vscode-cpptools) repository as it appeared on +2025-12-04. The last commit was by user michelleangela on 2020-01-09. The file is licensed under the +MIT license. + +* [`gcc.json`](https://github.com/microsoft/vscode-cpptools/blob/acdd5ca9d21cb1dda535594bee461beb9e8a5f06/Extension/package.json) + +The following problem matcher for yapf came from the [Google +SCAAML](https://github.com/google/scaaml) repository as it appeared on 2025-12-08. The last commit +was by user jmichelp on 2022-07-03. The file is licensed under the Apache 2.0 license. + +* [`yapf.json`](https://github.com/google/scaaml/blob/6d9c3a42c527212ef77f2877419dd8f6e77eb442/.github/python_matcher.json) diff --git a/.github/problem-matchers/gcc.json b/.github/problem-matchers/gcc.json new file mode 100644 index 000000000..edb58c80c --- /dev/null +++ b/.github/problem-matchers/gcc.json @@ -0,0 +1,17 @@ +{ + "problemMatcher": [ + { + "owner": "gcc", + "pattern": [ + { + "regexp": "^(.*):(\\d+):(\\d+):\\s+(?:fatal\\s+)?(warning|error):\\s+(.*)$", + "file": 1, + "line": 2, + "column": 3, + "severity": 4, + "message": 5 + } + ] + } + ] +} diff --git a/.github/problem-matchers/pytest.json b/.github/problem-matchers/pytest.json new file mode 100644 index 000000000..f6bbfba32 --- /dev/null +++ b/.github/problem-matchers/pytest.json @@ -0,0 +1,16 @@ +{ + "problemMatcher": [ + { + "owner": "pytest", + "severity": "error", + "pattern": [ + { + "regexp": "^(\\S+):(\\d+): (.*)$", + "file": 1, + "line": 2, + "message": 3 + } + ] + } + ] +} diff --git a/.github/problem-matchers/yapf.json b/.github/problem-matchers/yapf.json new file mode 100644 index 000000000..5c72ce5bc --- /dev/null +++ b/.github/problem-matchers/yapf.json @@ -0,0 +1,22 @@ +{ + "problemMatcher": [ + { + "owner": "yapf-diff", + "pattern": [ + { + "regexp": "^---\\s*([^\\s]*)\\s*\\(original\\)$", + "file": 1 + }, + { + "regexp": "^\\+\\+\\+\\s*([^\\s]*)\\s*\\((.*)\\)$", + "message": 2 + }, + { + "regexp": "^@@\\s*-(\\d+),(\\d+)\\s*\\+(\\d+),(\\d+)\\s*@@$", + "line": 1 + } + ] + }, + } + ] +} From 38688360218ed8f2b2643caf32835a66618b8b09 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 01:05:38 +0000 Subject: [PATCH 11/19] Add a TOC at the top of CONTRIBUTING.md --- CONTRIBUTING.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67aaf6619..2b5bb88bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,14 @@ Welcome, and thank you for your interest in contributing to our project! We're excited to work with you. To ensure a smooth and effective collaboration, please follow these guidelines. -## Getting Started +Table of contents quick links: + +* [Getting started](#getting-started) +* [Development process](#development-process) +* [Coding conventions](#coding-conventions) +* [Contribution workflow](#contribution-workflow) + +## Getting started Before you write any code, please complete the following steps. This will set you up for success and ensure your contributions can be merged smoothly. From 3cf0e1309dee1d6c2c513346acf4ff67b514ea9d Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 01:06:03 +0000 Subject: [PATCH 12/19] Add config file for `markdownlint` --- .markdownlintrc | 159 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 .markdownlintrc diff --git a/.markdownlintrc b/.markdownlintrc new file mode 100644 index 000000000..c23efc10d --- /dev/null +++ b/.markdownlintrc @@ -0,0 +1,159 @@ +{ // -*- jsonc -*- + // + // Copyright 2025 Google LLC + // + // Licensed under the Apache License, Version 2.0 (the "License"); + // you may not use this file except in compliance with the License. + // You may obtain a copy of the License at + // + // https://www.apache.org/licenses/LICENSE-2.0 + // + // Unless required by applicable law or agreed to in writing, software + // distributed under the License is distributed on an "AS IS" BASIS, + // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + // See the License for the specific language governing permissions and + // limitations under the License. + + // IMPORTANT: if you change values here, update .editorconfig to match. + + // These settings try to stay close to the Google Markdown Style as + // described at https://google.github.io/styleguide/docguide/style.html + // with very few differences. + + // Note: there are multiple programs programs named "markdownlint". We use + // https://github.com/igorshubovych/markdownlint-cli/, which is the one you + // get with "brew install markdownlint" on MacOS. + // + // For a list of possible configuration options, see the following page: + // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md + // (Beware that the above looks similar but is NOT the same as the page + // https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md.) + + "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json", + + // Require ATX-style headings. + // https://google.github.io/styleguide/docguide/style.html#atx-style-headings + "headings": { + "style": "atx" + }, + + // Google style does not require that the first line of a file is a heading + // for the title; it only states that the first heading should be a level 1. + // https://google.github.io/styleguide/docguide/style.html#document-layout + "first-line-heading": false, + + // The Google style does not define what to do about trailing punctuation in + // headings. The markdownlint default disallows exclamation points, which + // seems likely to be more annoying than useful – I have definitely seen + // people use exclamation points in headings in README files on GitHub. + // This setting removes exclamation point from the banned characters. + "no-trailing-punctuation": { + "punctuation": ".,;:。，；：" + }, + + // No trailing spaces. + // https://google.github.io/styleguide/docguide/style.html#trailing-whitespace + "whitespace": { + "br_spaces": 0 + }, + + // Google style is 80 characters. + // Google style exempts some constructs from the line-length limit: + // https://google.github.io/styleguide/docguide/style.html#exceptions + "line-length": { + "line_length": 80, + "code_block_line_length": 80, + "heading_line_length": 80, + "code_blocks": false, + "headings": false, + "tables": false + }, + + // Google Markdown style specifies 2 spaces after item numbers, 3 spaces + // after bullets, so that the text itself is consistently indented 4 spaces. + // https://google.github.io/styleguide/docguide/style.html#nested-list-spacing + "list-marker-space": { + "ol_multi": 2, + "ol_single": 2, + "ul_multi": 3, + "ul_single": 3 + }, + + "ul-indent": { + "indent": 4 + }, + + // Bare URLs are allowed in GitHub-flavored Markdown and in Google’s style. + "no-bare-urls": false, + + // Basic Markdown allows raw HTML. Both GitHub & PyPI support subsets of + // HTML, though it's unclear what subset PyPI supports. Google's style guide + // recommends against using raw HTML, but does allow it. (C.f. the bottom of + // https://google.github.io/styleguide/docguide/style.html) Google's in-house + // documentation system allows many inline and block-level tags, but strips + // others that can pose security risks (e.g., and standalone ). + // The list below tries to capture the intersection of what GitHub allows + // (c.f. https://github.com/github/markup/issues/245#issuecomment-682231577), + // what PyPI seems to allow, what Google allows, and what seems likely to be + // most useful in situations where someone needs to reach for HTML. + "html": { + "allowed_elements": [ + "a", + "abbr", + "b", + "blockquote", + "br", + "caption", + "cite", + "code", + "dd", + "del", + "details", + "dfn", + "div", + "dl", + "dt", + "em", + "figcaption", + "figure", + "h1", + "h2", + "h3", + "h4", + "h5", + "h6", + "hr", + "i", + "img", + "ins", + "kbd", + "li", + "mark", + "ol", + "p", + "picture", + "pre", + "q", + "s", + "samp", + "small", + "span", + "strong", + "sub", + "summary", + "sup", + "table", + "tbody", + "td", + "tfoot", + "th", + "thead", + "time", + "tr", + "tt", + "ul", + "var", + "wbr" + ] + } +} From 434215f114afeb344b509e4367febe39020af527 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 03:10:25 +0000 Subject: [PATCH 13/19] Fix minor typos and grammatical flaws --- CONTRIBUTING.md | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b5bb88bc..bd06fe166 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,7 +97,7 @@ Install the tools described in the [install TensorFlow Quantum]( docs/install.md) guide's section on how to build from source. The required tools include Python version 3.10 or greater, as well as [git](https://git-scm.com/), [pip](https://pip.pypa.io/en/stable/), a working Clang or GCC compiler toolchain -that supports C++ 17, and [Bazel](https://bazel.build/) version 6.5.0. +that supports C++17, and [Bazel](https://bazel.build/) version 6.5.0. ### Setting up a local development environment @@ -133,7 +133,7 @@ that supports C++ 17, and [Bazel](https://bazel.build/) version 6.5.0. Once the TFQ dependencies have been installed as described in the previous section, you should be able to build TFQ with these steps: -1. Run the configuration script +1. Run the configuration script: ```shell ./configure.sh @@ -170,15 +170,15 @@ Quantum from source](docs/install.md) section of the TFQ installation guide. ### Running tests locally While working on changes, and especially before doing git commits, use the -following scripts to check that TensorFlow Quantum continues to run correctly -and code conforms to this project's [coding conventions](#coding-conventions): +following scripts to check that TFQ continues to run correctly and that code +conforms to this project's [coding conventions](#coding-conventions): 1. `./scripts/test_all.sh`. We use TensorFlow's testing suite for our testing; be sure to follow the structure they have [outlined](https://www.tensorflow.org/api_docs/python/tf/test). 2. `./scripts/lint_all.sh`. We use [pylint](https://www.pylint.org/) to - ensure that code has proper formatting and is lint free. + ensure that code has proper formatting and is free of lint. 3. `./scripts/format_check.sh`. We use [yapf](https://github.com/google/yapf) along with @@ -221,13 +221,13 @@ TensorFlow Quantum follows the [TensorFlow code style](https://www.tensorflow.org/community/contribute/code_style). Briefly: * For Python, we follow the [PEP 8 Python style - guide](https://www.python.org/dev/peps/pep-0008/), and the [Google Python + guide](https://www.python.org/dev/peps/pep-0008/) and the [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md), except that TensorFlow uses 2 spaces instead of 4. * For C++ code and Protobuf definitions, we follow the [Google C++ Style - Guide](https://google.github.io/styleguide/cppguide.html) and [TensorFlow - specific style + Guide](https://google.github.io/styleguide/cppguide.html) and + [TensorFlow-specific specific style details](https://github.com/tensorflow/community/blob/master/governance/cpp-style.md). * For shell scripts, we follow the [Google Shell Style Guide]( @@ -262,15 +262,14 @@ and other programming language files. For other kinds of comments, follow these guidelines: -* _Write clear and concise comments_: Comments should explain the "why", not - the "what". The comments should explain the intent, trade-offs, and +* _Write clear and concise comments_: Comments should explain the "why," not + the "what." The comments should explain the intent, trade-offs, and reasoning behind the implementation. * _Comment sparingly_: Well-written code should be self-documenting where - possible. It's not necessary to add comments for code fragments that can - reasonably be assumed to be self-explanatory. + possible. Avoid adding comments for code that is self-explanatory. -* _Use complete sentences_: Start comments with a capital letter, use +* _Use complete sentences_: Start comments with a capital letter and use proper punctuation and correct grammar. ### Git commit do's and don't's @@ -284,11 +283,11 @@ changes easier with tools like `git cherry-pick` and `git rebase`. A commit should: * Represent a single, self-contained change, such as a specific bug fix or - addition of a specific feature. It should not combine unrelated changes, + the addition of a specific feature. It should not combine unrelated changes, and reverting it 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 + 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. @@ -317,7 +316,7 @@ to see if your idea or bug has been discussed before. * _For new ideas_: If your idea isn't covered by an existing issue, please **open a new issue to discuss your proposed changes before starting work**. - This ensures we agree on the approach before you invest more time. + This ensures we can agree on the approach before you invest more time. ### Develop your changes @@ -358,7 +357,7 @@ already forked the repo and [set up your development environment](#dev-env).) fork on GitHub: ```shell - git push origin + git push origin SOME-BRANCH-NAME ``` 2. Open a [**draft** pull request (PR)]( From ebf857860beb7fcdf63ebf96b72ee0ddb015f9d4 Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 18:30:34 +0000 Subject: [PATCH 14/19] Add a step to run `git config blame.ignoreRevsFile` In preparation for a separate PR to do nothing but reformat a few files, this adds information telling developers how to configure git to ignore specific commits. (This is the same approach used in Cirq.) This also adds a placeholder `.git-blame-ignore-revs` file for now, so that running the git config command does not result in an error. --- .git-blame-ignore-revs | 9 +++++++++ CONTRIBUTING.md | 11 +++++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 .git-blame-ignore-revs diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 000000000..30555188b --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,9 @@ +# Usage: run the following command to configure git to use this file: +# +# git config blame.ignoreRevsFile .git-blame-ignore-revs +# +# Summary: `git-blame` can be instructed to ignore certain commits. This is +# useful to do for commits that only involve large refactoring and reformatting +# operations. The format of this file is one full 40-character commit hash +# (SHA-1) per line. Blank lines and comments (such as this) are allowed. +# ============================================================================== diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd06fe166..da341aad0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -113,7 +113,14 @@ that supports C++17, and [Bazel](https://bazel.build/) version 6.5.0. cd quantum ``` -3. Set up a Python virtual environment. Here is an example of doing that with +3. Configure git to ignore certain commits (such as large reformatting or + refactoring operations) when producing output from `git blame`: + + ```shell + git config blame.ignoreRevsFile .git-blame-ignore-revs + ``` + +4. Set up a Python virtual environment. Here is an example of doing that with Python's built-in [venv](https://docs.python.org/3/library/venv.html), but you can use other methods and tools if you are more comfortable with them: @@ -122,7 +129,7 @@ that supports C++17, and [Bazel](https://bazel.build/) version 6.5.0. source quantum_env/bin/activate ``` -4. Install the TFQ Python requirements into the virtual environment: +5. Install the TFQ Python requirements into the virtual environment: ```shell pip install -r requirements.txt From 571cc0bd3f5ca36f3bbfb3f1c85f2a045c5ede1b Mon Sep 17 00:00:00 2001 From: mhucka Date: Tue, 9 Dec 2025 21:32:46 +0000 Subject: [PATCH 15/19] Use `python`, not `python3` Thanks to Pablo Samano Elton for catching that. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da341aad0..612702b9c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,7 +125,7 @@ that supports C++17, and [Bazel](https://bazel.build/) version 6.5.0. you can use other methods and tools if you are more comfortable with them: ```shell - python3 -m venv quantum_env + python -m venv quantum_env source quantum_env/bin/activate ``` From d3faf87c57a278c19caaa603cb894e734e124cfd Mon Sep 17 00:00:00 2001 From: mhucka Date: Thu, 11 Dec 2025 04:51:47 +0000 Subject: [PATCH 16/19] Say that bug reports are a valid type of contribution --- CONTRIBUTING.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 612702b9c..b4cea3dd2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -67,7 +67,21 @@ License Agreement (CLA)](https://cla.developers.google.com/). Only original works from you and other people who signed the CLA can be merged into this project. -### Finding opportunities to make contributions +### Look for opportunities to make contributions + +Contributions to this project can take many forms. + +#### Bug reports + +Navigate to the [Issues tab](https://github.com/tensorflow/quantum/issues) on +GitHub and click on the _New issue_ button. When reporting problems, please make +sure to include: + +* A clear description of the problem +* Steps necessary to reproduce the problem +* System information (operating system, version of TFQ) + +#### Code contributions/patches/pull requests The best way to get started is by tackling an existing issue. @@ -81,6 +95,16 @@ The best way to get started is by tackling an existing issue. 3. Once you pick an issue, leave a comment to let others know you are working on it. This helps prevent duplicated effort. +#### Feature requests + +Navigate to the [Issues tab](https://github.com/tensorflow/quantum/issues) on +GitHub and click on the _New issue_ button. When reporting problems, please make +sure to include: + +* A clear explanation of the feature you would like +* Approaches or solutions you have thought of +* System information (if relevant) + ## Development process This section describes the development process: From 309ba47bd6f7452b7c0e0202dc5a603cc3133f16 Mon Sep 17 00:00:00 2001 From: mhucka Date: Thu, 11 Dec 2025 04:53:48 +0000 Subject: [PATCH 17/19] Mention that we use Apache 2.0 --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4cea3dd2..401dcb812 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -287,9 +287,9 @@ level of the TensorFlow Quantum repository. ### Comment conventions -Every source file must begin with a header comment containing a copyright -statement and license. License headers are necessary in Python, C++, Bash/shell, -and other programming language files. +This project uses the Apache 2.0 license. Every source file must begin with a +header comment containing a copyright statement and license. License headers are +necessary in Python, C++, Bash/shell, and other programming language files. For other kinds of comments, follow these guidelines: From e5d094b8b02890d08fa877ef670e7eefcf1c3b3b Mon Sep 17 00:00:00 2001 From: mhucka Date: Thu, 11 Dec 2025 05:01:21 +0000 Subject: [PATCH 18/19] Add a bit more info to the contributor workflow --- CONTRIBUTING.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 401dcb812..bb08d0829 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -303,7 +303,7 @@ For other kinds of comments, follow these guidelines: * _Use complete sentences_: Start comments with a capital letter and use proper punctuation and correct grammar. -### Git commit do's and don't's +### Git commit do's and don't's We strive to follow the principles of granular commits. Making smaller, focused commits has many benefits: changes are easier for reviewers to understand and @@ -374,14 +374,20 @@ already forked the repo and [set up your development environment](#dev-env).) git checkout -b SOME-BRANCH-NAME ``` -3. Make your changes. Remember to write and run tests for your changes. Commit - changes often. Write small, focused commits with clear messages. +3. Make your changes. Follow the project [coding + conventions](#coding-conventions). Commit changes often and follow the + guidelines for [Git commit do's and don't's](#git-commits). Write small, + focused commits with clear messages. ```shell git add -A git commit ``` +4. Remember to write and run tests for your changes. Run the [scripts for + testing changes locally](#running-tests-locally) to make sure everything + works. + ### Submit your changes for review 1. Once you are done with a particular piece of work, push your changes to your From 4db7c6a937212c169aa64af45bffe9cdbdbc10e7 Mon Sep 17 00:00:00 2001 From: mhucka Date: Thu, 11 Dec 2025 05:22:50 +0000 Subject: [PATCH 19/19] Add back some cxxopt flags that shouldn't have been deleted --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb08d0829..421367cbb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -173,7 +173,7 @@ section, you should be able to build TFQ with these steps: 2. Build a pip package for TFQ: ```shell - bazel build -c opt release:build_pip_package + bazel build -c opt --cxxopt="-O3" --cxxopt="-march=native" release:build_pip_package bazel-bin/release/build_pip_package /tmp/tfquantum/ ```