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