From d71dae510a932d6b89eb126fe1e28209e222bd3d Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Sat, 26 Feb 2022 19:05:16 -0600 Subject: [PATCH] Update, copyedit and format README and Contributing Guide (#2352) --- CONTRIBUTING.rst | 60 ++++++++++++++++++++++-------------------------- README.rst | 56 +++++++++++++++++++++++--------------------- 2 files changed, 57 insertions(+), 59 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 541bcd8166e..108f0efdf9a 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,30 +1,29 @@ Contributing Guidelines ======================= -To learn more about the purpose of PEPs and how to go about writing a PEP, please -start reading at PEP 1 (`pep-0001.txt <./pep-0001.txt>`_ in this repo). Note that -PEP 0, the index PEP, is now automatically generated, and not committed to the repo. +To learn more about the purpose of PEPs and how to go about writing one, please +start reading at `PEP 1 `_. +Also, make sure to check the `README <./README.rst>`_ for information +on how to render the PEPs in this repository. +Thanks again for your contributions, and we look forward to reviewing them! + Before writing a new PEP ------------------------ -Has this idea been proposed on `python-ideas `_ -and received general acceptance as being an idea worth pursuing? (if not then -please start a discussion there before submitting a pull request). - -More details about it in `PEP 1 `_. +Prior to submitting a pull request here with your draft PEP, see `PEP 1 +`_ +for some important steps to consider, including proposing and discussing it +first in an appropriate venue, drafting a PEP and gathering feedback, and +developing at least a prototype reference implementation of your idea. -Do you have an implementation of your idea? (this is important for when you -propose this PEP to `python-dev `_ -as code maintenance is a critical aspect of all PEP proposals prior to a -final decision; in special circumstances an implementation can be deferred) +Commit messages and PR titles +----------------------------- -Commit messages ---------------- - -When committing to a PEP, please always include the PEP number in the subject -title. For example, ``PEP NNN: ``. +When adding or modifying a PEP, please always include the PEP number in the +commit summary and pull request title. +For example, ``PEP NNN: ``. Sign the CLA @@ -32,16 +31,11 @@ Sign the CLA Before you hit "Create pull request", please take a moment to ensure that this project can legally accept your contribution by verifying you have signed the -PSF Contributor Agreement: - - https://www.python.org/psf/contrib/contrib-form/ - -If you haven't signed the CLA before, please follow the steps outlined in the -CPython devguide to do so: - - https://devguide.python.org/pullrequest/#licensing +`PSF Contributor Agreement `_. -Thanks again to your contribution and we look forward to looking at it! +If you haven't signed the CLA before, please follow the +`steps outlined in the CPython devguide +`_ to do so. Code of Conduct @@ -49,7 +43,7 @@ Code of Conduct 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 +expected to be open, considerate, and respectful of others, no matter their position within the project. @@ -76,27 +70,27 @@ before running this command. Otherwise, you can install pre-commit with -.. code-block:: console +.. code-block:: bash 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 +.. code-block:: bash pre-commit run --all-files or only on any files that have been modified but not yet committed with -.. code-block:: console +.. code-block:: bash 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 +.. code-block:: bash pre-commit install @@ -119,13 +113,13 @@ 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 +.. code-block:: bash pre-commit run --hook-stage manual codespell or against all files with -.. code-block:: console +.. code-block:: bash pre-commit run --all-files --hook-stage manual codespell diff --git a/README.rst b/README.rst index 00b511eeb2b..8178cb34450 100644 --- a/README.rst +++ b/README.rst @@ -6,9 +6,10 @@ Python Enhancement Proposals The PEPs in this repo are published automatically on the web at https://www.python.org/dev/peps/. To learn more about the purpose of -PEPs and how to go about writing a PEP, please start reading at PEP 1 -(``pep-0001.txt`` in this repo). Note that PEP 0, the index PEP, is -now automatically generated, and not committed to the repo. +PEPs and how to go about writing one, please start reading at `PEP 1 +`_. +Note that PEP 0, the index PEP, is +automatically generated and not committed to the repo. Contributing to PEPs @@ -20,16 +21,18 @@ See the `Contributing Guidelines <./CONTRIBUTING.rst>`_. reStructuredText for PEPs ========================= -Original PEP source should be written in reStructuredText format, +PEP source text should be written in reStructuredText format, which is a constrained version of plaintext, and is described in -PEP 12. Older PEPs were often written in a more mildly restricted -plaintext format, as described in PEP 9. The ``pep2html.py`` -processing and installation script knows how to produce the HTML -for either PEP format. +`PEP 12 `_. +The ``pep2html.py`` processing and installation script knows +how to produce the HTML for the PEP format. -For processing reStructuredText format PEPs, you need the docutils -package, which is available from `PyPI `_. -If you have pip, ``pip install docutils`` should install it. +To render the PEPs, you'll first need to install the requirements, +(preferably in a fresh virtual environment): + +.. code-block:: bash + + python -m pip install -r requirements.txt Generating the PEP Index @@ -49,13 +52,13 @@ 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, -.. code-block:: console +.. code-block:: bash python pep2html.py pep-0012.rst If you're on a system with ``make``, you can instead execute, e.g., -.. code-block:: console +.. code-block:: bash make pep-0012.rst @@ -78,24 +81,25 @@ 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 +Generating HTML for Python.org ============================== -python.org includes its own helper modules to render PEPs as HTML, with +Python.org includes its own helper modules to render PEPs as HTML, with suitable links back to the source pages in the version control repository. -These can be found at https://github.com/python/pythondotorg/tree/main/peps +These can be found `in the python.org repository +`__. When making changes to the PEP management process that may impact python.org's rendering pipeline: -* Clone the python.org repository from https://github.com/python/pythondotorg/ -* Get set up for local python.org development as per - https://pythondotorg.readthedocs.io/install.html#manual-setup +* Clone the `python.org repository `_. +* Get `set up for local python.org development + `_. * Adjust ``PEP_REPO_PATH`` in ``pydotorg/settings/local.py`` to refer to your - local clone of the PEP repository -* Run ``./manage.py generate_pep_pages`` as described in - https://pythondotorg.readthedocs.io/pep_generation.html + local clone of the PEP repository. +* Run ``./manage.py generate_pep_pages`` as described the `python.org docs + `__. Rendering PEPs with Sphinx @@ -119,19 +123,19 @@ instructions on how to install, build and view the rendered PEPs with Sphinx. In summary, after installing the dependencies (preferably in a virtual environment) with: -.. code-block:: console +.. code-block:: bash python -m pip install -r requirements.txt You can build the PEPs with sphinx by running, if your system has ``make``: -.. code-block:: console +.. code-block:: bash make sphinx Otherwise, execute the ``build.py`` script directly: -.. code-block:: console +.. code-block:: bash python build.py @@ -143,6 +147,6 @@ The output HTML can be found under the ``build`` directory. For details on the command-line options to the ``build.py`` script, run: -.. code-block:: console +.. code-block:: bash python build.py --help