diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 73051001c5a..60294d46e2e 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -7,7 +7,6 @@
# PEP infrastructure
.github/workflows/ @AA-Turner @CAM-Gerlach
-.pre-commit-config.yaml @CAM-Gerlach
Makefile @AA-Turner
requirements.txt @AA-Turner
@@ -24,6 +23,15 @@ conf.py @AA-Turner
contents.rst @AA-Turner
generate_rss.py @AA-Turner
+# Linting infrastructure
+.codespell/ @CAM-Gerlach @hugovk
+.codespellrc @CAM-Gerlach @hugovk
+.pre-commit-config.yaml @CAM-Gerlach @hugovk
+
+# Git infrastructure
+.gitattributes @CAM-Gerlach
+.gitignore @CAM-Gerlach
+
pep-0001.txt @warsaw @ncoghlan
pep-0001-process_flow.png @warsaw @ncoghlan
pep-0001/ @warsaw @ncoghlan
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 8f01b5802d2..541bcd8166e 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -51,3 +51,88 @@ All interactions for this project are covered by the
`PSF Code of Conduct `_. Everyone is
expected to be open, considerate, and respectful of others no matter their
position within the project.
+
+
+Run pre-commit linting locally
+------------------------------
+
+You can run this repo's basic linting suite locally,
+either on-demand, or automatically against modified files
+whenever you commit your changes.
+
+They are also run in CI, so you don't have to run them locally, though doing
+so will help you catch and potentially fix common mistakes before pushing
+your changes and opening a pull request.
+
+This repository uses the `pre-commit `_ tool to
+install, configure and update a suite of hooks that check for
+common problems and issues, and fix many of them automatically.
+
+If your system has ``make`` installed, you can run the pre-commit checkers
+on the full repo by running ``make lint``. This will
+install pre-commit in the current virtual environment if it isn't already,
+so make sure you've activated the environment you want it to use
+before running this command.
+
+Otherwise, you can install pre-commit with
+
+.. code-block:: console
+
+ python -m pip install pre-commit
+
+(or your choice of installer), and then run the hooks on all the files
+in the repo with
+
+.. code-block:: console
+
+ pre-commit run --all-files
+
+or only on any files that have been modified but not yet committed with
+
+.. code-block:: console
+
+ pre-commit run
+
+If you would like pre-commit to run automatically against any modified files
+every time you commit, install the hooks with
+
+.. code-block:: console
+
+ pre-commit install
+
+Then, whenever you ``git commit``, pre-commit will run and report any issues
+it finds or changes it makes, and abort the commit to allow you to check,
+and if necessary correct them before committing again.
+
+
+Check and fix PEP spelling
+--------------------------
+
+To check for common spelling mistakes in your PEP and automatically suggest
+corrections, you can run the codespell tool through pre-commit as well.
+
+Like the linters, on a system with ``make`` available, it can be installed
+(in the currently-activated environment) and run on all files in the
+repository with a single command, ``make spellcheck``.
+
+For finer control or on other systems, after installing pre-commit as in
+the previous section, you can run it against only the files
+you've modified and not yet committed with
+
+.. code-block:: console
+
+ pre-commit run --hook-stage manual codespell
+
+or against all files with
+
+.. code-block:: console
+
+ pre-commit run --all-files --hook-stage manual codespell
+
+**Note**: While fixing spelling mistakes as part of more substantive
+copyediting and proofreading of draft and active PEPs is okay,
+we generally advise against PRs that simply mass-correct minor typos on
+older PEPs that don't significantly impair meaning and understanding,
+as these tend to create a fairly high level of noise and churn for
+PEP readers, authors and editors relative to the amount of practical value
+they provide.
diff --git a/Makefile b/Makefile
index f81adf9f5cc..bdf0752d83f 100644
--- a/Makefile
+++ b/Makefile
@@ -52,11 +52,11 @@ package: all rss
tar -C build -czf build/peps.tar.gz peps
lint:
- pre-commit --version > /dev/null || python3 -m pip install pre-commit
+ pre-commit --version > /dev/null || $(PYTHON) -m pip install pre-commit
pre-commit run --all-files
spellcheck:
- pre-commit --version > /dev/null || python3 -m pip install pre-commit
+ pre-commit --version > /dev/null || $(PYTHON) -m pip install pre-commit
pre-commit run --all-files --hook-stage manual codespell
# New Sphinx targets:
diff --git a/README.rst b/README.rst
index c435d3fffcb..6b5231327b8 100644
--- a/README.rst
+++ b/README.rst
@@ -43,13 +43,39 @@ libraries in the ``pep0`` directory.
Checking PEP formatting and rendering
=====================================
-Do not commit changes with bad formatting. To check the formatting of
-a PEP, use the Makefile. In particular, to generate HTML for PEP 9999,
-your source code should be in ``pep-9999.rst`` and the HTML will be
-generated to ``pep-9999.html`` by the command ``make pep-9999.html``.
-The default Make target generates HTML for all PEPs.
+Please don't commit changes with reStructuredText syntax errors that cause PEP
+generation to fail, or result in major rendering defects relative to what you
+intend. To check building the HTML output for your PEP (for example, PEP 12)
+using the current default docutils-based system, run the ``pep2html.py`` script
+with your PEP source file as its argument; e.g. for PEP 12,
-If you don't have Make, use the ``pep2html.py`` script directly.
+.. code-block:: console
+
+ python pep2html.py pep-0012.rst
+
+If you're on a system with ``make``, you can instead execute, e.g.,
+
+.. code-block:: console
+
+ make pep-0012.rst
+
+To generate HTML for all the PEPs, run the script/``make`` without a PEP
+file argument.
+
+By default, this will output a file (e.g. ``pep-0012.html``) in the root
+directory, which you can view to see the HTML output of your PEP.
+Note that the custom CSS stylesheet is not used by default, so
+the PEP will look rather plain, but all the basic formatting produced by the
+reStructuredText syntax in your source file should be visible.
+
+You can also view your PEP locally with the Sphinx-based builder,
+which will show the PEP exactly as it will appear on the preview
+of the new rendering system proposed in :pep:`676`;
+see `Rendering PEPs with Sphinx`_ for details.
+
+Finally, you can check for and fix common linting and spelling issues,
+either on-demand or automatically as you commit, with our pre-commit suite.
+See the `Contributing Guide <./CONTRIBUTING.rst>`_ for details.
Generating HTML for python.org