Edit CONTRIBUTING.md

CONTRIBUTING.md

@@ -1,11 +1,9 @@
 # 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 OpenFermion an open and welcoming
-environment.
+some guidelines to follow, covered in this document, but don't be concerned
+about getting everything right the first time! Create a pull request (discussed
+below) and we'll nudge you in the right direction.
 
 ## Before you begin
 
@@ -14,35 +12,61 @@ environment.
 Contributions to this project must be accompanied by a [Contributor License
 Agreement](https://cla.developers.google.com/about) (CLA). You (or your
 employer) retain the copyright to your contribution; the CLA simply gives us
-permission to use and redistribute your contributions as part of this project.
-
-If you or your current employer have already signed the Google CLA (even if it
-was for a different project), you probably don't need to do it again.
-
-Visit <https://cla.developers.google.com/> to see your current agreements or to
-sign a new one.
+permission to use and redistribute your contributions as part of the project.
+Please visit https://cla.developers.google.com/ to see your current agreements
+on file or to sign a new one. You generally only need to submit a Google CLA
+once, so if you've already submitted one (even if it was for a different
+project), you probably don't need to do it again.
+
+> [!WARNING]
+> Please note carefully clauses [#5](https://cla.developers.google.com/about/google-corporate#:~:text=You%20represent%20that%20each%20of%20Your%20Contributions%20is%20Your%20original%20creation)
+> and [#7](https://cla.developers.google.com/about/google-corporate#:~:text=Should%20You%20wish%20to%20submit%20work%20that%20is%20not%20Your%20original%20creation%2C%20You%20may%20submit%20it%20to%20Google%20separately)
+> in the CLA. Any code that you contribute to this project must be **your**
+> original creation. Code generated by artificial intelligence tools **does
+> not** qualify as your original creation.
 
 ### Review our community guidelines
 
-This project follows [Google's Open Source Community
-Guidelines](https://opensource.google/conduct/).
+We have a [code of conduct](CODE_OF_CONDUCT.md) to make the project an open and
+welcoming community environment. Please make sure to read and abide by the code
+of conduct.
 
 ## Contribution process
 
-### Code reviews
-
 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.
+use the tools provided by GitHub for pull requests for this purpose. The
+preferred manner for submitting pull requests is to fork the, create a new
+branch in this fork to do your work, and when ready, create a pull request from
+this branch to the main project repository. The subsections below describe the
+process in more detail.
+
+Pleae make sure to follow the [Google Style
+Guides](https://google.github.io/styleguide/) in your code, particularly the
+[style guide for Python](https://google.github.io/styleguide/pyguide.html).
+
+### Repository forks
+
+1.  Fork the OpenFermion repository (you can use the _Fork_ button in upper
+    right corner of the [repository
+    page](https://github.com/quantumlib/OpenFermion)). Forking creates a new
+    GitHub repo at the location `https://github.com/USERNAME/OpenFermion`, where
+    `USERNAME` is your GitHub user name.
+
+1.  Clone (using `git clone`) or otherwise download your forked repository to
+    your local computer, so that you have a local copy where you can do your
+    development work using your preferred editor and development tools.
+
+1.  Check out the `main` branch and create a new [git
+    branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell)
+    from `main`:
+
+    ```shell
+    git checkout main -b YOUR_BRANCH_NAME
+    ```
 
-The preferred approach for submitting pull requests is for developers to fork
-the OpenFermion [GitHub repository](https://github.com/quantumlib/OpenFermion)
-and then use a [git
-branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell)
-from the fork to create a pull request to the main OpenFermion repo.
+    where `YOUR_BRANCH_NAME` is the name of your new branch.
 
-### Development environment setup
+### Development environment installation
 
 Please refer to the section _Developer install_ of the [installation
 instructions](docs/install.md) for information about how to set up a local copy
@@ -58,24 +82,68 @@ scripts [`./check/pytest`](./check/pytest) and
 [`./check/pytest-and-incremental-coverage`](./check/pytest-and-incremental-coverage)
 to run these programs with custom configurations for this project.
 
-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.
+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,
-and the script [`./check/pylint`](./check/pylint) to run it. 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.
+constructs. We use [Pylint](https://www.pylint.org/) to check for code lint, and
+the script [`./check/pylint`](./check/pylint) to run it. 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
+### Type annotations
 
 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, and the script [`./check/mypy`](./check/mypy) to run it. When type
-checking produces a false positive, it can be silenced with annotations such as
-`# type: ignore`.
+We use [mypy](http://mypy-lang.org/) to check that type annotations are correct,
+and the script [`./check/mypy`](./check/mypy) to run it. When type checking
+produces a false positive, it can be silenced with annotations such as `# type:
+ignore`.
+
+### Pull requests and code reviews
+
+1.  If your local copy has drifted out of sync with the `main` branch of the
+    main OpenFermion repo, you may need to merge 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/OpenFermion.git
+
+    # Update your local main.
+    git fetch upstream
+    git checkout main
+    git merge upstream/main
+    # Merge local main into your branch.
+    git checkout YOUR_BRANCH_NAME
+    git merge main
+    ```
+
+    If git reports conflicts during one or both of these merge processes, you
+    may need to [resolve the merge conflicts](
+    https://docs.github.com/articles/about-merge-conflicts) before continuing.
+
+1.  Finally, push your changes to your fork of the OpenFermion repo on GitHub:
+
+    ```shell
+    git push origin YOUR_BRANCH_NAME
+    ```
+
+1.  Now when you navigate to the OpenFermion repository on GitHub
+    (https://github.com/quantumlib/OpenFermion), you should see the option to
+    create a new [pull
+    requests](https://help.github.com/articles/about-pull-requests/) from your
+    forked 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 from the OpenFermion team will comment on your code and may ask
+    for changes. You can perform the necessary changes locally, commit them to
+    your branch as usual, and then push changes to your fork on GitHub following
+    the same process as above. When you do that, GitHub will update the code in
+    the pull request automatically.