docs: Revise contributing.rst

Tighten step-by-step instructions, fix comma splices, and standardize
heading capitalization in contributing.rst.

Change-Id: I3c8b3ba699b9a3064f025dc8a4b63ad40e4f7844
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
index f1e9f99..babbe38 100644
--- a/docs/source/contributing.rst
+++ b/docs/source/contributing.rst
@@ -5,141 +5,129 @@
 ============
 
 We welcome contributions to Ceres, whether they are new features, bug
-fixes or tests. The Ceres `mailing
-<https://groups.google.com/g/ceres-solver>`_ list is the best place
-for all development related discussions. Please consider joining
-it. If you have ideas on how you would like to contribute to Ceres, it
-is a good idea to let us know on the mailing list before you start
-development. We may have suggestions that will save effort when trying
-to merge your work into the main branch. If you are looking for ideas,
-please let us know about your interest and skills and we will be happy
-to make a suggestion or three.
+fixes, or tests. The `Ceres mailing list
+<https://groups.google.com/g/ceres-solver>`_ is the best place for
+development discussions. If you plan to contribute a new feature or
+significant change, please post your proposal on the mailing list
+before starting development; early feedback often saves effort during
+code review. If you are looking for a project, tell us about your
+interests and background on the mailing list and we will be glad to
+suggest open problems.
 
 We follow Google's `C++ Style Guide
-<https://google.github.io/styleguide/cppguide.html>`_ and
-use `git <https://git-scm.com/>`_ for version control. We use
-`Gerrit <https://ceres-solver-review.googlesource.com/>`_ to collaborate and
-review changes to Ceres. Gerrit enables pre-commit reviews so that
-Ceres can maintain a linear history with clean, reviewed commits, and
-no merges.
+<https://google.github.io/styleguide/cppguide.html>`_ and use `git
+<https://git-scm.com/>`_ for version control. Code review takes place
+on `Gerrit <https://ceres-solver-review.googlesource.com/>`_, which
+enables pre-commit review so that Ceres maintains a linear history of
+clean, reviewed commits without merge commits.
 
-We now describe how to set up your development environment and submit
-a change list for review via Gerrit.
+The sections below describe how to set up your development environment
+and submit a change list for review on Gerrit.
 
-Setting up your Environment
+Setting up Your Environment
 ===========================
 
-1. Download and configure ``git``.
+1. Download and configure ``git``:
 
-   * Mac ``brew install git``.
-   * Linux ``sudo apt-get install git``.
-   * Windows. Download `Git for Windows
+   * macOS: ``brew install git``
+   * Linux: ``sudo apt-get install git``
+   * Windows: Download `Git for Windows
      <https://git-scm.com/download/win>`__.
 
 2. Sign up for `Gerrit
-   <https://ceres-solver-review.googlesource.com/>`_. You will also need to
-   `sign the Contributor License Agreement (CLA)
-   <https://opensource.google/documentation/reference/cla>`_ with Google, which gives
-   Google a royalty-free unlimited license to use your contributions. You
-   retain copyright.
+   <https://ceres-solver-review.googlesource.com/>`_ and `sign the
+   Google Contributor License Agreement (CLA)
+   <https://opensource.google/documentation/reference/cla>`_, which
+   grants Google a royalty-free, unlimited license to use your
+   contributions while you retain copyright.
 
-3. Clone the Ceres Solver ``git`` repository from Gerrit.
+3. Clone the Ceres Solver ``git`` repository from Gerrit:
 
    .. code-block:: bash
 
       git clone https://ceres-solver.googlesource.com/ceres-solver
 
 
-4. Build Ceres, following the instructions in
+4. Build Ceres following the instructions in
    :ref:`chapter-installation`.
 
-   On Mac and Linux, the ``CMake`` build will download and enable
-   the Gerrit pre-commit hook automatically. This pre-submit hook
-   creates ``Change-Id: ...`` lines in your commits.
+   On macOS and Linux, the ``CMake`` build automatically downloads and
+   installs the Gerrit ``commit-msg`` hook, which appends a
+   ``Change-Id: ...`` line to each commit message.
 
-   If this does not work OR you are on Windows, execute the
-   following in the root directory of the local ``git`` repository:
+   If the hook is not installed automatically, or if you are on
+   Windows, run the following commands in the root directory of your
+   local ``git`` repository:
 
    .. code-block:: bash
 
       curl -o .git/hooks/commit-msg https://ceres-solver-review.googlesource.com/tools/hooks/commit-msg
       chmod +x .git/hooks/commit-msg
 
-5. Configure your Gerrit password with a ``.gitcookies`` which allows pushing
-   to Gerrit without having to enter a very long random password every time:
+5. Configure a ``.gitcookies`` file so that you can push to Gerrit
+   without entering a generated password each time:
 
-   * Sign into `https://ceres-solver-review.googlesource.com
+   * Sign in to `https://ceres-solver-review.googlesource.com
      <https://ceres-solver-review.googlesource.com>`_.
 
    * Click ``Settings -> HTTP Credentials -> Obtain Password``.
 
-   * (maybe) Select an account for multi-login. This should be the
-     same as your Gerrit login.
+   * If prompted by multi-login, select the account associated with
+     your Gerrit login.
 
-   * Click ``Allow access`` when the page requests access to your
+   * Click ``Allow access`` when prompted to grant access to your
      ``git`` repositories.
 
-   * Follow the instructions from Gerrit to create a ``.gitcookies`` file on
-     your system, either in ``$HOME/.gitcookies`` (Mac and Linux) or
-     ``%USERPROFILE%\.gitcookies`` (Windows). Note that for Windows, please get
-     a recent `Git for Windows <https://git-scm.com/download/win>`_ install to
-     enable automatic lookup in the ``%USERPROFILE%\.gitcookies``.
+   * Follow the instructions on the page to create a ``.gitcookies``
+     file in ``$HOME/.gitcookies`` (macOS and Linux) or
+     ``%USERPROFILE%\.gitcookies`` (Windows). On Windows, use a recent
+     release of `Git for Windows <https://git-scm.com/download/win>`_
+     so that ``%USERPROFILE%\.gitcookies`` is detected automatically.
 
-6. Install ``clang-format``.
+6. Install ``clang-format``:
 
-   * Mac ``brew install clang-format``.
-   * Linux ``sudo apt-get install clang-format``.
-   * Windows. You can get clang-format with `clang or stand-alone via
-     npm <https://superuser.com/a/1505297/1141693>`_.
+   * macOS: ``brew install clang-format``
+   * Linux: ``sudo apt-get install clang-format``
+   * Windows: Install ``clang-format`` via Visual Studio, LLVM, or
+     `npm <https://superuser.com/a/1505297/1141693>`_.
 
-   You can ensure all sources files are correctly formatted before
-   committing by manually running ``clang-format -i FILENAME``, by
-   running the script ``./scripts/format_all.sh``, or by configuring
-   your editor to format upon saving.
+   Format all modified source files before committing by running
+   ``clang-format -i FILENAME``, executing ``./scripts/format_all.sh``,
+   or configuring your editor to run ``clang-format`` on save.
 
-Submitting a change
+Submitting a Change
 ===================
 
-1. Make your changes against master or whatever branch you
-   like. Ensure that the changes are formatted according to
-   ``clang-format``. Commit your changes as one patch. When you
-   commit, the Gerrit hook will add a ``Change-Id:`` line as the last
-   line of the commit.
+1. Make your changes against ``master`` (or a local branch) and format
+   them with ``clang-format``. Commit your changes as a single logical
+   patch; the Gerrit hook will append a ``Change-Id:`` footer to the
+   commit message.
 
-   Make sure that your commit message is formatted in the `50/72 style
+   Format your commit message in the standard `50/72 style
    <https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
 
-2. Push your changes to the Ceres Gerrit instance:
+2. Push your commit to Gerrit for review:
 
    .. code-block:: bash
 
       git push origin HEAD:refs/for/master
 
-   When the push succeeds, the console will display a URL showing the
-   address of the review. Go to the URL and add at least one of the
-   maintainers (Sameer Agarwal, Keir Mierle, Alex Stewart, William
-   Rucklidge or Sergiu Deitsch) as reviewers.
+   When the push succeeds, ``git`` prints the URL of the Gerrit review.
+   Open that URL and add at least one maintainer (Sameer Agarwal, Keir
+   Mierle, Alex Stewart, William Rucklidge, or Sergiu Deitsch) as a
+   reviewer.
 
-3. Wait for a review.
+3. Wait for review feedback.
 
-4. Once review comments come in, address them. Please reply to each
-   comment in Gerrit, which makes the re-review process easier. After
-   modifying the code in your ``git`` instance, *don't make a new
-   commit*. Instead, update the last commit using a command like the
-   following:
+4. Address any review comments and reply to each comment thread in
+   Gerrit. Instead of creating a second commit, amend your existing
+   commit so that the ``Change-Id:`` line is preserved:
 
    .. code-block:: bash
 
       git commit --amend -a
 
-   This will update the last commit, so that it has both the original
-   patch and your updates as a single commit. You will have a chance
-   to edit the commit message as well. Push the new commit to Gerrit
-   as before.
-
-   Gerrit will use the ``Change-Id:`` to match the previous commit
-   with the new one. The review interface retains your original patch,
-   but also shows the new patch.
-
-   Publish your responses to the comments, and wait for a new round
-   of reviews.
+   Push the amended commit to ``HEAD:refs/for/master`` again. Gerrit
+   uses the ``Change-Id:`` footer to attach the new patch set to the
+   existing review while preserving earlier patch sets for comparison.
+   Publish your replies on Gerrit to notify the reviewers.