Merge branch 'master' into mh-fix-contributing.md

Author: mhucka

.editorconfig

@@ -1,27 +1,94 @@
-# Summary: coding style configuration for editors that read .editorconfig.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Common editor configurations for this project.
 #
 # EditorConfig defines a file format for specifying some common coding style
-# parameters. Many editors recognize .editorconfig files automatically, and
-# there exist plugins for other editors. See https://spec.editorconfig.org/.
+# parameters. Many IDEs and editors read .editorconfig files, either natively
+# or via plugins. A few formatters also read .editorconfig; shfmt and Prettier
+# are two examples (as of early 2025).
+#
+# We mostly follow Google's style guides (https://google.github.io/styleguide/)
+# with very few deviations.
+#
+# Miscellaneous notes:
+#
+# - The EditorConfig property `max_line_length` is not set here because its
+#   intended behavior is poorly specified. (See the discussion in the comments
+#   at https://github.com/editorconfig/editorconfig/issues/387) It *would* have
+#   been desirable to define a project convention for the line width here, but
+#   we must instead use editor-specific configuration files to do that.
+#
+# - With few exceptions (e.g., shfmt), `.editorconfig` files are not read by
+#   linters or formatters, which means the project needs separate config files
+#   for those tools. This includes markdownlint, yamllint, and others.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 root = true
 
 [*]
 charset = utf-8
-end_of_line = lf
+indent_style = space
 insert_final_newline = true
 spelling_language = en-US
+# It would be preferable not to set tab_width, but some EditorConfig plugins
+# (e.g., Emacs's) set it equal to indent_size if it's not set otherwise.
+tab_width = 8
+# Trailing whitespace on lines is almost always noise. An exception is in
+# Markdown, where two spaces = line break; however, that's such a foot-gun in
+# practice that we avoid it. So, it's okay to set this next value globally.
 trim_trailing_whitespace = true
 
+[{BUILD,*.BUILD,*.bzl,*.bazel}]
+# Google doesn't have a style guideline for Bazel files. Most people use 4.
+indent_size = 4
+
+[{*.cc,*.h}]
+# This matches Google style guidelines.
+indent_size = 2
+
+[{*.ts,*.js}]
+# This matches Google style guidelines.
+indent_size = 2
+
+[*.json]
+# Not stated explicitly in Google's guidelines, but the examples use 2.
+indent_size = 2
+
 [*.py]
+# This matches Google style guidelines.
 indent_size = 4
-indent_style = space
-max_line_length = 100
+
+[*.rst]
+# Google doesn't have a style guideline for reStructuredText. Many people use 3.
+indent_size = 3
 
 [*.sh]
+# Google style guidelines use 2.
 indent_size = 4
-indent_style = space
-max_line_length = 100
+# The following are used by shfmt. These bring it closer to Google's style.
+binary_next_line = true
+shell_variant = bash
+space_redirects = true
+switch_case_indent = true
+
+# If this repository has a "third_party" directory, ignore it entirely.
+# Note: shfmt also respects this if you run it with --appply-ignore.
+[third_party/**]
+ignore = true
 
-[*.yml,*.yaml]
+[{*.yaml,*.yml}]
+# Google doesn't have style guidelines for YAML. Most people use indent = 2.
 indent_size = 2

.github/workflows/ci.yaml

@@ -1,4 +1,19 @@
-# Summary: OpenFermion continuous integration status checks.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# OpenFermion continuous integration status checks.
 #
 # This workflow runs various tests to verify that changes to the OpenFermion
 # codebase pass validation and conform to project format and style standards.

.github/workflows/codeql.yaml

@@ -1,3 +1,18 @@
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # Zero-configuration modular workflow to run CodeQL code scans.
 #
 # CodeQL is a semantic code analysis tool that finds vulnerabilities by

.github/workflows/nightly-pytest.yaml

@@ -1,4 +1,19 @@
-# Summary: reusable workflow called by nightly.yaml.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Reusable workflow called by nightly.yaml.
 # This workflow expects input values passed by nightly.yml.
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

.github/workflows/nightly.yaml

@@ -1,4 +1,19 @@
-# Summary: run nightly tests and scans.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Nightly tests and scans workflow.
 #
 # This workflow runs nightly to run tests & scans on the OpenFermion codebase.
 # It can also be invoked manually via the "Run workflow" button at

.github/workflows/osv-scanner.yaml

@@ -1,3 +1,18 @@
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # Zero-config modular workflow to run Open Source Vulnerabilities code scans.
 #
 # The OSV scanner is a dependency vulnerability scanner that identifies known

.github/workflows/scorecard.yaml

@@ -1,3 +1,18 @@
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 # Zero-configuration modular workflow to run the OSSF Scorecard scanner.
 #
 # Scorecard (https://github.com/ossf/scorecard) is a repository-scanning tool

.gitignore

@@ -1,3 +1,17 @@
+# 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.
+
 .DS_Store
 *lastfailed
 

.hadolint.yaml

@@ -1,5 +1,21 @@
-# Summary: configuration for hadolint used in CI checks.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Hadolint (Dockerfile linter) used in this project's CI checks.
 # Info about options can be found at https://github.com/hadolint/hadolint/.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 format: tty
 no-color: false

.markdownlintrc

@@ -1,11 +1,28 @@
-{ // Summary: markdownlint config file for Quantumlib projects    -*- jsonc -*-
+{ // -*- 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.
+
+  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  // Markdownlint linter configuration for this project.
   //
   // 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.
   //
   // 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.
   //
   // For a list of configuration options, see the following page:
   // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
@@ -41,9 +58,13 @@
     "br_spaces": 0
   },
 
-  // Google style exempts some constructs from the line-length limit of 80 chars.
+  // 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": 100,
+    "code_block_line_length": 100,
+    "heading_line_length": 100,
     "code_blocks": false,
     "headings": false,
     "tables": false
@@ -67,24 +88,20 @@
   "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 doesn't disallow using HTML, although it recommends against it. (C.f.
-  // the bottom of https://google.github.io/styleguide/docguide/style.html)
-  // It's worth noting, though, that Google's guidance has Google's internal
-  // documentation system in mind, and that system extends Markdown with
-  // constructs that make it possible to accomplish things you can't do in
-  // Markdown. Those extensions are also not available outside Google's system.
-  // Thus, although a goal of this markdownlint configuration is to match
-  // Google's style guide as closely as possible, these various factors suggest
-  // it's reasonable to relax the HTML limitation. The list below is based on
-  // https://github.com/github/markup/issues/245#issuecomment-682231577 plus
-  // some things found elsewhere after that was written.
+  // 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., <object> and standalone <svg>).
+  // 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",
-      "bdo",
       "blockquote",
       "br",
       "caption",
@@ -106,8 +123,6 @@
       "h4",
       "h5",
       "h6",
-      "h7",
-      "h8",
       "hr",
       "i",
       "img",
@@ -120,16 +135,10 @@
       "picture",
       "pre",
       "q",
-      "rp",
-      "rt",
-      "ruby",
       "s",
       "samp",
       "small",
-      "source",
-      "span",
       "span",
-      "strike",
       "strong",
       "sub",
       "summary",
@@ -145,7 +154,6 @@
       "tt",
       "ul",
       "var",
-      "video",
       "wbr"
     ]
   }