Reformat miscellaneous .md files outside of docs/ (#6999)

* Reformat & mildly edit CONTRIBUTING.md

1) Reformat to follow Google Markdown style guidelines.
2) Make very small edits in a few places for clarification and
   consistency.

* Reformat & edit release.md

1) Reformat to follow Google Markdown style guidelines.
2) Edit the text for (hopefully) improved clarity.
3) Fix minor typos.

* Reformat md -- no content change

Reformatted using markdownlint.

* Reformat md & make trivial edit

Reformatted using markdownlint, and made a minor edit to the first
sentence.

* Reformat md and add a link

* Reformat and make corrections & edits

* Reformat md

* Reformat md to following Google Markdown style

Ran files through markdownlint and manually corrected some things.

* Delete trailing whitespace

Per comment by @Pavol at #6999 (review)

* Use a more descriptive title

Per suggestion by @Pavol at #6999 (comment)

Author: mhucka

CONTRIBUTING.md

@@ -1,11 +1,11 @@
 # How to Contribute
 
-We'd love to accept your patches and contributions to this project.
-We do have some guidelines to follow, covered in this document, but don't
-worry about (or expect to) get everything right the first time!
-Create a pull request and we'll nudge you in the right direction. Please also
-note that we have a [code of conduct](CODE_OF_CONDUCT.md) to make Cirq an
-open and welcoming community environment.
+We'd love to accept your patches and contributions to this project. We do have
+some guidelines to follow, covered in this document, but don't worry about –
+or expect to – get everything right the first time! Create a pull request
+(discussed below) and we'll nudge you in the right direction. Please also note
+that we have a [code of conduct](CODE_OF_CONDUCT.md) to make Cirq an open and
+welcoming community environment.
 
 ## Contributor License Agreement
 
@@ -30,26 +30,32 @@ information on using pull requests.
 The preferred manner for submitting pull requests is for developers to fork
 the Cirq [repository](https://github.com/quantumlib/Cirq) and then use a [git
 branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell)
-from this fork to create a pull request to the main Cirq repo. The basic process for setting
-up a fork is as follows:
-
-1. Fork the Cirq repository (you can use the _Fork_ button in upper right
-corner of the [repository page](https://github.com/quantumlib/Cirq)).
-Forking creates a new GitHub repo at the location
-`https://github.com/USERNAME/Cirq`, where `USERNAME` is
-your GitHub user name. Use the instructions on the
-[development page](docs/dev/development.md) to download a copy to
-your local machine. You need only do this once.
-1. Check out the `main` branch and create a new branch from `main`:
+from this fork to create a pull request to the main Cirq repo. The basic
+process for setting up a fork is as follows:
+
+1.  Fork the Cirq repository (you can use the _Fork_ button in upper right
+    corner of the [repository page](https://github.com/quantumlib/Cirq)).
+    Forking creates a new GitHub repo at the location
+    `https://github.com/USERNAME/Cirq`, where `USERNAME` is
+    your GitHub user name. Use the instructions on the Cirq
+    [development page](docs/dev/development.md) to download a copy to
+    your local machine. You need only do this once.
+
+1.  Check out the `main` branch and create a new branch from `main`:
+
     ```shell
     git checkout main -b new_branch_name
     ```
+
     where `new_branch_name` is the name of your new branch.
-1. Do your work and commit your changes to this branch.
-1. If your local copy has drifted out of sync with the `main` branch of the
-main Cirq repo, you may need to merge in the latest changes.  To do this,
-first update your local `main` and then merge your local `main`
-into your branch:
+
+1.  Do your work and commit your changes to this branch.
+
+1.  If your local copy has drifted out of sync with the `main` branch of the
+    main Cirq repo, you may need to merge in the latest changes into your
+    branch.  To do this, first update your local `main` and then merge your
+    local `main` into your branch:
+
     ```shell
     # Track the upstream repo (if your local repo hasn't):
     git remote add upstream https://github.com/quantumlib/Cirq.git
@@ -62,22 +68,26 @@ into your branch:
     git checkout new_branch_name
     git merge main
     ```
+
     You may need to fix [merge conflicts](
     https://docs.github.com/articles/about-merge-conflicts)
     during one or both of these merge processes.
-1. Finally, push your changes to your forked copy of the Cirq repo on GitHub:
+
+1.  Finally, push your changes to your forked copy of the Cirq repo on GitHub:
+
     ```shell
     git push origin new_branch_name
     ```
-1. Now when you navigate to the Cirq repository on GitHub
-(https://github.com/quantumlib/Cirq),
-you should see the option to create a new pull request from
-your clone repository.  Alternatively, you can create the pull request
-by navigating to the "Pull requests" tab in the page, and selecting
-the appropriate branches.
-1. A reviewer will comment on your code and may ask for changes.
-You can perform the necessary changes locally, and then push the new commit
-following the same process as above.
+
+1.  Now when you navigate to the Cirq repository on GitHub
+    (https://github.com/quantumlib/Cirq), you should see the option to create a
+    new pull request from your clone repository.  Alternatively, you can create
+    the pull request by navigating to the "Pull requests" tab near the top of
+    the page, and selecting the appropriate branches.
+
+1.  A reviewer will comment on your code and may ask for changes. You can
+    perform the necessary changes locally, and then push the new commit
+    following the same process as above.
 
 ## Development Environment Setup
 
@@ -97,28 +107,34 @@ integration checks locally.
 Please be aware of the following coding standards that will be applied to any
 new changes.
 
-- **Tests**.
+### Tests
+
 Existing tests must continue to pass (or be updated) when new changes are
 introduced. We use [pytest](https://docs.pytest.org) to run our
 tests.
-- **Coverage**.
-Code should be covered by tests.
-We use [pytest-cov](https://pytest-cov.readthedocs.io) to compute
-coverage, and custom tooling to filter down the output to only include new or
-changed code. We don't require 100% coverage, but any uncovered code must
-be annotated with `# pragma: no cover`. To ignore coverage of a single line,
-place `# pragma: no cover` at the end of the line. To ignore coverage for
-an entire block, start the block with a `# pragma: no cover` comment on its
-own line.
-- **Lint**.
+
+### Coverage
+
+Code should be covered by tests. We use
+[pytest-cov](https://pytest-cov.readthedocs.io) to compute coverage, and custom
+tooling to filter down the output to only include new or changed code. We don't
+require 100% coverage, but any uncovered code must be annotated with `# pragma:
+no cover`. To ignore coverage of a single line, place `# pragma: no cover` at
+the end of the line. To ignore coverage for an entire block, start the block
+with a `# pragma: no cover` comment on its own line.
+
+### Lint
+
 Code should meet common style standards for Python and be free of error-prone
 constructs. We use [Pylint](https://www.pylint.org/) to check for code lint.
 To see which lint checks we enforce, see the
 [dev_tools/conf/.pylintrc](dev_tools/conf/.pylintrc) file. When Pylint produces
 a false positive, it can be silenced with annotations. For example, the
 annotation `# pylint: disable=unused-import` would silence a warning about
 an unused import.
-- **Types**.
+
+### Types
+
 Code should have [type annotations](https://www.python.org/dev/peps/pep-0484/).
 We use [mypy](http://mypy-lang.org/) to check that type annotations are correct.
 When type checking produces a false positive, it can be silenced with
@@ -127,7 +143,7 @@ annotations such as `# type: ignore`.
 ## Request For Comment Process for New Major Features
 
 For larger contributions that will benefit from design reviews, please use the Cirq
-[Request for Comment](docs/dev/rfc_process.md) process.
+[Request for Comment](docs/dev/rfc_process.md) (RFC) process.
 
 ## Developing notebooks
 

benchmarks/README.md

@@ -1,22 +1,36 @@
 # Cirq Performance Benchmarks
-Performance benchmarking Cirq with [Airspeed Velocity](https://asv.readthedocs.io/en/stable/index.html).
+
+This directory concerns doing Cirq performance benchmarks with [Airspeed
+Velocity](https://asv.readthedocs.io/en/stable/index.html).
 
 ## Overview
-The benchmark files (`bench_*.py`) stored in the current package (`benchmarks/*`) are used by asv to run benchmark tests for Cirq. For more information on how to write new benchmarks, please refer [Writing benchmarks guide by ASV](https://asv.readthedocs.io/en/stable/writing_benchmarks.html)
+
+The benchmark files (`bench_*.py`) stored in the current package
+(`benchmarks/*`) are used by ASV to run benchmark tests for Cirq. For more
+information on how to write new benchmarks, please refer [Writing benchmarks
+guide by ASV](https://asv.readthedocs.io/en/stable/writing_benchmarks.html)
 
 ## Usage
-To run all benchmarks, navigate to the root Cirq directory at the command line and execute
+
+To run all benchmarks, navigate to the root Cirq directory at the command line
+and execute the following command:
 
 ```bash
 ./check/asv_run
 ```
 
-You can also pass arguments to the script, which would be forwarded to the `asv run` command. For eg:
+You can also pass arguments to the `asv_run` script, which will be forwarded to
+the `asv run` command. Here's an example:
+
 ```bash
 ./check/asv_run --quick --bench bench_examples --python 3.10
 ```
 
-Please refer [Running Benchmarks guide by ASV](https://asv.readthedocs.io/en/stable/using.html#running-benchmarks) for more information. 
+Please refer to [Running Benchmarks guide by
+ASV](https://asv.readthedocs.io/en/stable/using.html#running-benchmarks) for
+more information.
 
 ## Results Database
-TODO([#3838](https://github.com/quantumlib/Cirq/issues/3838)): Add details regarding GCP setup.
+
+TODO([#3838](https://github.com/quantumlib/Cirq/issues/3838)): Add details
+regarding GCP setup.

cirq-core/cirq/protocols/json_test_data/README.md

@@ -1,3 +1,5 @@
-This folder contains test data for cirq's JSON serialization functionality.
+# JSON test data for Cirq serialization tests
 
-For more information, see [`docs/dev/serialization.md`](/docs/dev/serialization.md).
+This folder contains test data for Cirq's JSON serialization functionality. For
+more information, please see
+[`docs/dev/serialization.md`](/docs/dev/serialization.md).

cirq-google/cirq_google/devices/specifications/README.md

@@ -1,6 +1,9 @@
+# Device specifications of Google quantum processors
+
 This directory contains snapshots of `DeviceSpecification` proto messages
-(defined in `cirq-google/cirq_google/api/v2/device.proto`) describing Google devices.
+(defined in `cirq-google/cirq_google/api/v2/device.proto`) describing Google
+devices.
 
-Files with the suffix `_for_grid_device` are equivalent representations of corresponding proto files
-without the suffix, but in the new `DeviceSpecification` format which is parsed into
-`cirq_google.GridDevice`.
+Files with the suffix `_for_grid_device` are equivalent representations of
+corresponding proto files without the suffix, but in the new
+`DeviceSpecification` format which is parsed into `cirq_google.GridDevice`.

cirq-google/version_policy.md

@@ -1,3 +1,7 @@
 # cirq-google Version Policy
 
-The `cirq-google` directory should abide by Semantic Versioning 2.0.0. In rare cases, we may introduce backward-incompatible changes to the public API in a release with a minor version increment. Such changes will be noted in `CHANGELOG.md` within the directory before the release.
+The `cirq-google` directory should abide by the [Semantic Versioning
+2.0.0](https://semver.org/) principles. In rare cases, we may introduce
+backward-incompatible changes to the public API in a release with a minor
+version increment. Such changes will be noted in `CHANGELOG.md` within the
+directory before the release.