clarify pre-commits and editing workflow

story645 · story645 · commit 863cf89966af · 2023-08-23T02:40:14.000-04:00
diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst
@@ -164,16 +164,27 @@ true for ``*.py`` files.  If you change the C-extension source (which might
 also happen if you change branches) you will have to re-run
 ``python -m pip install -ve .``
 
-Install pre-commit hooks (optional)
-===================================
-`pre-commit <https://pre-commit.com/>`_ hooks automatically check flake8 and
-other style issues when you run ``git commit``. The hooks are defined in the
-top level ``.pre-commit-config.yaml`` file. To install the hooks ::
+Install pre-commit hooks
+========================
+`pre-commit <https://pre-commit.com/>`_ hooks save time in the review process by
+identifying issues with the code before a pull request is formally opened. Most
+hooks can also aide in fixing the errors, and the checks should have
+corresponding :ref:`development workflow <development-workflow>` and
+:ref:`pull request <pr-guidelines>` guidelines. Hooks are configured in
+`.pre-commit-config.yaml <https://github.com/matplotlib/matplotlib/blob/main/.pre-commit-config.yaml?>`_
+and include checks for spelling and formatting, flake 8 conformity, accidentally
+committed files, import order, and incorrect branching.
+
+Install pre-commit hooks ::
 
     python -m pip install pre-commit
     pre-commit install
 
-The hooks can also be run manually. All the hooks can be run, in order as
+Hooks are run automatically after the ``git commit`` stage of the
+:ref:`editing workflow<edit-flow>`. When a hook has found and fixed an error in a
+file, that file must be *staged and committed* again.
+
+Hooks can also be run manually. All the hooks can be run, in order as
 listed in ``.pre-commit-config.yaml``, against the full codebase with ::
 
     pre-commit run --all-files
diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst
@@ -95,20 +95,8 @@ request and open a new pull request from the renamed branch. See
 The editing workflow
 ====================
 
-Overview
---------
-
-::
-
-   # hack hack
-   git add my_new_file
-   git commit -am 'NF - some message'
-   git push
-
-In more detail
---------------
-
 #. Make some changes
+#. Save the changes
 #. See which files have changed with ``git status``.
    You'll see a listing like this one:
 
@@ -129,13 +117,17 @@ In more detail
 
 #. Check what the actual changes are with ``git diff``.
 #. Add any new files to version control ``git add new_file_name``.
-#. To commit all modified files into the local copy of your repo,, do
-   ``git commit -am 'A commit message'``.  Note the ``-am`` options to
-   ``commit``. The ``m`` flag just signals that you're going to type a
-   message on the command line.  The ``a`` flag — you can just take on
-   faith — or see `why the -a flag?`_. The
-   `git commit <https://git-scm.com/docs/git-commit>`_ manual page might also be
-   useful.
+#. To commit **all** modified files into the local copy of your repo, type:
+
+   .. code-block:: bash
+
+      git commit -am 'A commit message'
+
+   Note the ``-am`` options to ``commit``. The ``m`` flag signals that you are
+   going to type a message on the command line.  The ``a`` flag stages every
+   file that has been modified, except files listed in ``.gitignore``. For more
+   information, see `why the -a flag?`_ and the
+   `git commit <https://git-scm.com/docs/git-commit>`_  manual page.
 #. To push the changes up to your forked repo on GitHub, do a ``git
    push``.
 
