From 6dfa2b3fa2e61086183c214565ed25357800bee5 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 16 Feb 2022 20:21:56 -0600 Subject: [PATCH 1/7] Add and consolidate codeowners for linting infrastructure --- .github/CODEOWNERS | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 73051001c5a..e86087a1ac4 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,13 @@ conf.py @AA-Turner contents.rst @AA-Turner generate_rss.py @AA-Turner +# Linting infrastructure +.codespell/ @CAM-Gerlach +.codespellrc @CAM-Gerlach +.pre-commit-config.yaml @CAM-Gerlach +.gitattributes @CAM-Gerlach +.gitignore @CAM-Gerlach + pep-0001.txt @warsaw @ncoghlan pep-0001-process_flow.png @warsaw @ncoghlan pep-0001/ @warsaw @ncoghlan From 945b213d149baf85de6668b8724b7a8cd3e53353 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 16 Feb 2022 21:15:22 -0600 Subject: [PATCH 2/7] Update Makefile to use alias for lint and spellcheck jobs --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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: From efb7b460c9a640974e2683098c98f61cd2b25bdc Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 16 Feb 2022 21:00:23 -0600 Subject: [PATCH 3/7] Update the README to provide more detail on checking PEP rendering --- README.rst | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index c435d3fffcb..26f0fc61108 100644 --- a/README.rst +++ b/README.rst @@ -43,13 +43,27 @@ 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. - -If you don't have Make, use the ``pep2html.py`` script directly. +Avoid committing changes with reStructuredText syntax errors that cause PEP +generation to fail, or result in major rendering defects relative to what +you intend. To build 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, +``python -X dev pep2html.py pep-0012.rst``, +If you're on a system with ``make``, you can instead simply execute, e.g., +``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. Generating HTML for python.org From 250f98e7ede7b84e7b8870fe91a114ec1958c969 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 16 Feb 2022 21:26:28 -0600 Subject: [PATCH 4/7] Add explaination for how to use pre-commit in Contributing Guide --- CONTRIBUTING.rst | 33 +++++++++++++++++++++++++++++++++ README.rst | 4 ++++ 2 files changed, 37 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8f01b5802d2..b352f1d9464 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -51,3 +51,36 @@ 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 +------------------------------ + +If you'd like, you can run the project's basic linting suite locally, +either on-demand when you choose, 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 simply running ``make lint``. Note that 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 by running ``pip install pre-commit`` +(or your choice of installer), and then run the hooks on all the files +in the repo with ``pre-commit run --all-files``, or only on any files that +have been modified but not yet committed with ``pre-commit run``. + +If you would like pre-commit to run automatically against any modified files +every time you commit, install the hooks with ``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. diff --git a/README.rst b/README.rst index 26f0fc61108..8bd121b12e0 100644 --- a/README.rst +++ b/README.rst @@ -65,6 +65,10 @@ 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 ============================== From b88d05219b40c3aa67107cb1381848e6ceb1388b Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 17 Feb 2022 20:44:18 -0600 Subject: [PATCH 5/7] Add section to Contributing Guide on how to check PEP spelling --- CONTRIBUTING.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b352f1d9464..a94b0385f7d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -84,3 +84,28 @@ every time you commit, install the hooks with ``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 above +(e.g. ``pip install pre-commit``), you can run it against only the files +you've modified and not yet committed with +``pre-commit run --hook-stage manual codespell``, or against all files with +``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. From 9ddc9a802a5219aaed60ca5035ad3891f2ea77bc Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Thu, 17 Feb 2022 20:36:07 -0600 Subject: [PATCH 6/7] Improve readme and contributing guide sections further with reviewer feedback Co-authored-by: Hugo van Kemenade --- .github/CODEOWNERS | 8 +++++--- CONTRIBUTING.rst | 10 +++++----- README.rst | 12 ++++++------ 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e86087a1ac4..60294d46e2e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -24,9 +24,11 @@ contents.rst @AA-Turner generate_rss.py @AA-Turner # Linting infrastructure -.codespell/ @CAM-Gerlach -.codespellrc @CAM-Gerlach -.pre-commit-config.yaml @CAM-Gerlach +.codespell/ @CAM-Gerlach @hugovk +.codespellrc @CAM-Gerlach @hugovk +.pre-commit-config.yaml @CAM-Gerlach @hugovk + +# Git infrastructure .gitattributes @CAM-Gerlach .gitignore @CAM-Gerlach diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a94b0385f7d..6a045a119a2 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -56,8 +56,8 @@ position within the project. Run pre-commit linting locally ------------------------------ -If you'd like, you can run the project's basic linting suite locally, -either on-demand when you choose, or automatically against modified files +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 @@ -69,12 +69,12 @@ 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 simply running ``make lint``. Note that this will +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 by running ``pip install pre-commit`` +Otherwise, you can install pre-commit by running ``python -m pip install pre-commit`` (or your choice of installer), and then run the hooks on all the files in the repo with ``pre-commit run --all-files``, or only on any files that have been modified but not yet committed with ``pre-commit run``. @@ -97,7 +97,7 @@ Like the linters, on a system with ``make`` available, it can be installed repository with a single command, ``make spellcheck``. For finer control or on other systems, after installing pre-commit as above -(e.g. ``pip install pre-commit``), you can run it against only the files +(e.g. ``python -m pip install pre-commit``), you can run it against only the files you've modified and not yet committed with ``pre-commit run --hook-stage manual codespell``, or against all files with ``pre-commit run --all-files --hook-stage manual codespell``. diff --git a/README.rst b/README.rst index 8bd121b12e0..875e765a8cd 100644 --- a/README.rst +++ b/README.rst @@ -43,13 +43,13 @@ libraries in the ``pep0`` directory. Checking PEP formatting and rendering ===================================== -Avoid committing changes with reStructuredText syntax errors that cause PEP -generation to fail, or result in major rendering defects relative to what -you intend. To build the HTML output for your PEP (for example, PEP 12) +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, -``python -X dev pep2html.py pep-0012.rst``, -If you're on a system with ``make``, you can instead simply execute, e.g., +with your PEP source file as its argument (e.g. for PEP 12, +``python pep2html.py pep-0012.rst``). +If you're on a system with ``make``, you can instead execute, e.g., ``make pep-0012.rst``. To generate HTML for all the PEPs, run the script/``make`` without a PEP file argument. From 6ec177e8f2656563fe6b82d82a7913ced3b3df0a Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 17 Feb 2022 20:59:22 -0600 Subject: [PATCH 7/7] Format check, lint & spelling commands in Readme/Contribguide as blocks --- CONTRIBUTING.rst | 43 +++++++++++++++++++++++++++++++++++-------- README.rst | 14 +++++++++++--- 2 files changed, 46 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6a045a119a2..541bcd8166e 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -74,13 +74,32 @@ 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 by running ``python -m pip install pre-commit`` +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 ``pre-commit run --all-files``, or only on any files that -have been modified but not yet committed with ``pre-commit run``. +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 ``pre-commit install``. +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. @@ -96,11 +115,19 @@ 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 above -(e.g. ``python -m pip install pre-commit``), you can run it against only the files +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 -``pre-commit run --hook-stage manual codespell``, or against all files with -``pre-commit run --all-files --hook-stage manual codespell``. + +.. 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, diff --git a/README.rst b/README.rst index 875e765a8cd..6b5231327b8 100644 --- a/README.rst +++ b/README.rst @@ -47,10 +47,18 @@ 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, -``python pep2html.py pep-0012.rst``). +with your PEP source file as its argument; e.g. for PEP 12, + +.. code-block:: console + + python pep2html.py pep-0012.rst + If you're on a system with ``make``, you can instead execute, e.g., -``make pep-0012.rst``. + +.. code-block:: console + + make pep-0012.rst + To generate HTML for all the PEPs, run the script/``make`` without a PEP file argument.