Add missing license headers & do minor updates to top-level dot files

.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]
+# This matches Google style guidelines.
 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/first-interaction.yaml

@@ -1,4 +1,19 @@
-# Summary: add a welcoming comment to first-time contributors' issues & PRs.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Add a welcoming comment to first-time contributors' issues & PRs.
 # This is written in a generic way so that we can use the same workflow
 # in all our quantumlib repos.
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.github/workflows/pytest-debug.yaml

@@ -1,5 +1,19 @@
+# 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.
+
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# Summary: GitHub workflow for manually running pytest with debug flags.
+# GitHub workflow for manually running pytest with debug flags.
 #
 # This workflow can only be executed manually, e.g., using the "Run workflow"
 # button on https://github.com/quantumlib/Cirq/actions/workflows/debug.yaml

.github/workflows/stale.yml

@@ -1,5 +1,21 @@
-# Summary: perform scheduled handling of stale issues and PRs.
-# For more info, see https://github.com/actions/stale/.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Perform scheduled handling of stale issues and PRs.
+# For info about possible config options, see https://github.com/actions/stale/.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 name: "Stale issues & PRs handler"
 

.markdownlintrc

@@ -1,11 +1,28 @@
-{ // Summary: markdownlint config file for Cirq                    -*- jsonc -*-
+{ // -*- jsonc -*-
+  // Copyright 2025 Google LLC
   //
-  // Note: there are multiple programs programs named "markdownlint". For
-  // Cirq, we use https://github.com/igorshubovych/markdownlint-cli/, which is
-  // the one you get with "brew install markdownlint" on MacOS.
+  // 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"
     ]
   }

.yamllint.yaml

@@ -1,5 +1,21 @@
-# Summary: yamllint configuration for Cirq.
+# 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.
+
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# Yamllint configuration to match project settings like line length.
 # See https://yamllint.readthedocs.io/ for info about configuration options.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 rules:
   line-length: