diff --git a/.clang-format b/.clang-format new file mode 100644 index 000000000..b164c4fcf --- /dev/null +++ b/.clang-format @@ -0,0 +1,20 @@ +# 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 diff --git a/.editorconfig b/.editorconfig index f93e4abe0..bbcf3e296 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,22 +11,15 @@ # 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. - -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -# 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 +28,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 +41,7 @@ indent_size = 2 indent_size = 4 [*.sh] -indent_size = 4 +indent_size = 2 -[*.yml,*.yaml] +[{*.yaml,*.yml,*.cff}] indent_size = 2 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/.gitattributes b/.gitattributes new file mode 100644 index 000000000..bbe425f1b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,24 @@ +# 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 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 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 + } + ] + }, + } + ] +} 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" + ] + } +} 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 new file mode 100644 index 000000000..b2ead2e19 --- /dev/null +++ b/.style.yapf @@ -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 yapf (https://github.com/google/yapf) for this project. + +[style] +based_on_style = google 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. 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d5b67e7e..421367cbb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,62 +1,416 @@ -# 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. +Table of contents quick links: -Please fill out either the individual or corporate Contributor License Agreement -(CLA). +* [Getting started](#getting-started) +* [Development process](#development-process) +* [Coding conventions](#coding-conventions) +* [Contribution workflow](#contribution-workflow) -* 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). +## Getting started -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. +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. -NOTE: Only original source code from you and other people that have signed the -CLA can be accepted into the main repository. +* Review our [community guidelines](#learn-our-community-guidelines) to + understand our commitment to a welcoming and harassment-free environment. -## Code Reviews +* Sign the [Contributor License Agreement (CLA)](#cla) to grant us permission + to use your work. -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. +* 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. -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 how to find [opportunities for contributions](#opportunities). -## Code Standards +* Understand our [development process](#development-process) and [contribution + workflow](#contribution-workflow). -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: +### Learn our community guidelines -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). +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. -2. `./scripts/lint_all.sh` passes. We use [pylint](https://www.pylint.org/) -to ensure that code has proper formatting and is lint free. +Our key principles include: -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. +* 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. -### Adding Modules +Please read our full [Code of Conduct](CODE_OF_CONDUCT.md) for more details. + +### Sign the Contributor License Agreement + +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. + +### 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. + +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. + +#### 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: + +* 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. 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: + + ```shell + python -m venv quantum_env + source quantum_env/bin/activate + ``` + +5. 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 --cxxopt="-O3" --cxxopt="-march=native" 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 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 free of lint. + +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 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 + +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: + +* _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. Avoid adding comments for code that is self-explanatory. + +* _Use complete sentences_: Start comments with a capital letter and 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 + 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 + 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 can 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. 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 + fork on GitHub: + + ```shell + git push origin SOME-BRANCH-NAME + ``` + +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. 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.