From 4742dac16978a0fb51106d41e7f1096ab41de61c Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 23 Feb 2022 00:00:22 -0600 Subject: [PATCH 1/4] PEP 1 & 12: Have Post-History actually link posts, not just list dates --- pep-0001.txt | 17 +++++++++-------- pep-0012.rst | 29 ++++++++++++++++++----------- pep-0012/pep-NNNN.rst | 2 +- 3 files changed, 28 insertions(+), 20 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 9958e0dff88..73d32524fcf 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -208,8 +208,8 @@ The standard PEP workflow is: * The title accurately describes the content. * The PEP's language (spelling, grammar, sentence structure, etc.) and code style (examples should match :pep:`7` & :pep:`8`) should be - correct and conformant. The PEP text will be automatically checked for - correct reStructuredText formatting when the pull request is submitted. + correct and conformant. The PEP text will be automatically checked for + correct reStructuredText formatting when the pull request is submitted. PEPs with invalid reST markup will not be approved. Editors are generally quite lenient about this initial review, @@ -286,13 +286,13 @@ the PEP Sponsor and PEP editors can advise them accordingly. If the chosen venue is not the `Python-Dev`_ mailing list, a brief announcement should be posted there when the draft PEP is committed to the PEP repository and available on the PEP website, -with a link to the rendered PEP and the to canonical Discussions-To thread. +with a link to the rendered PEP and to the canonical ``Discussions-To`` thread. If a PEP undergoes a significant re-write or other major, substantive changes to its proposed specification, a new thread should typically be created in the chosen venue to solicit additional feedback. If this occurs, the -``Discussions-To`` link and ``Post-History`` in the PEP must be updated to -reflect this new thread, and (if not the discussion venue) a further +``Discussions-To`` link must be updated and a new ``Post-History`` entry added +pointing to this new thread, and (if not the discussion venue) a further announcement sent to `Python-Dev`_ containing the same information as above and at least briefly summarizing the major changes. @@ -600,7 +600,8 @@ optional and are described below. All other headers are required. * Requires: Created: * Python-Version: - Post-History: + Post-History: * Replaces: * Superseded-By: * Resolution: @@ -656,8 +657,8 @@ compatibility, plain text is currently still the default if no Content-Type header is present. The Created header records the date that the PEP was assigned a -number, while Post-History is used to record the dates of when new -versions of the PEP are posted to Python-Dev and/or the Discussions-To thread. +number, while Post-History is used to record the dates of and corresponding +inline links to the Discussions-To threads for the PEP. Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001. Standards Track PEPs will typically have a Python-Version header which diff --git a/pep-0012.rst b/pep-0012.rst index 23d0591cf96..c363f8db078 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -7,7 +7,7 @@ Status: Active Type: Process Content-Type: text/x-rst Created: 05-Aug-2002 -Post-History: 30-Aug-2002 +Post-History: `30-Aug-2002 `_ .. note:: @@ -113,20 +113,25 @@ directions below. first appearance in. Do not use an alpha or beta release designation here. Thus, if the last version of Python was 2.2 alpha 1 and you're hoping to get your new feature into Python 2.2, set the - header to:: + header to: + + .. code-block:: email Python-Version: 2.2 -- Leave Post-History alone for now; you'll add dates to this header - each time you post your PEP to the designated discussion forum (and announce - it on Python-Dev, if needed; see the ``Discussions-To`` header above). +- Leave Post-History alone for now; you'll add dates and corresponding links + to this header each time you post your PEP to the designated discussion forum + (and update the ``Discussions-To`` header with said link, as above). If you posted threads for your PEP on August 14, 2001 and September 3, 2001, - the Post-History header would look like:: + the Post-History header would look something like: + + .. code-block:: email - Post-History: 14-Aug-2001, 03-Sept-2001 + Post-History: `14-Aug-2001 `_, + `03-Sept-2001 `_ - You must manually add new dates and commit them (with a pull request - if you don't have push privileges). + You must manually add new dates/links and commit them as soon as you post a + new discussion thread (with a pull request, if you don't have push rights). - Add a Replaces header if your PEP obsoletes an earlier PEP. The value of this header is the number of the PEP that your new PEP is @@ -152,7 +157,9 @@ directions below. For reference, here are all of the possible header fields (everything in brackets should either be replaced or have the field removed if it has a leading ``*`` marking it as optional and it does not apply to -your PEP):: +your PEP): + +.. code-block:: email PEP: [NNN] Title: [...] @@ -166,7 +173,7 @@ your PEP):: Requires: *[NNN] Created: [DD-MMM-YYYY] Python-Version: *[M.N] - Post-History: [DD-MMM-YYYY] + Post-History: [`DD-MMM-YYYY `_] Replaces: *[NNN] Superseded-By: *[NNN] Resolution: diff --git a/pep-0012/pep-NNNN.rst b/pep-0012/pep-NNNN.rst index 339fa7c4b32..c606237731f 100644 --- a/pep-0012/pep-NNNN.rst +++ b/pep-0012/pep-NNNN.rst @@ -9,7 +9,7 @@ Type: Requires: Created: Python-Version: -Post-History: +Post-History: Replaces: Superseded-By: Resolution: From 1e4984787081c1594709bbcee889cf70a65ca278 Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Thu, 24 Feb 2022 22:37:01 -0600 Subject: [PATCH 2/4] PEP 12: Eliminate unnecessary/redundant detail in Post-History instructions Co-authored-by: Jelle Zijlstra --- pep-0012.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep-0012.rst b/pep-0012.rst index c363f8db078..08428f96fda 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -130,8 +130,8 @@ directions below. Post-History: `14-Aug-2001 `_, `03-Sept-2001 `_ - You must manually add new dates/links and commit them as soon as you post a - new discussion thread (with a pull request, if you don't have push rights). + You must manually add new dates/links as soon as you post a + new discussion thread. - Add a Replaces header if your PEP obsoletes an earlier PEP. The value of this header is the number of the PEP that your new PEP is From e4c39c35fdb72579b73599f37b5381b9b0016e0c Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 2 Mar 2022 15:27:32 -0600 Subject: [PATCH 3/4] PEP 1/12: Clarify language around Post-History links & make anonymous --- pep-0001.txt | 7 ++++--- pep-0012.rst | 12 ++++++------ 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 73d32524fcf..f6caf0ffcdb 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -600,8 +600,8 @@ optional and are described below. All other headers are required. * Requires: Created: * Python-Version: - Post-History: + Post-History: * Replaces: * Superseded-By: * Resolution: @@ -658,7 +658,8 @@ Content-Type header is present. The Created header records the date that the PEP was assigned a number, while Post-History is used to record the dates of and corresponding -inline links to the Discussions-To threads for the PEP. +URLs to the Discussions-To threads for the PEP, with the former as the +linked text, and the latter as the link target. Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001. Standards Track PEPs will typically have a Python-Version header which diff --git a/pep-0012.rst b/pep-0012.rst index 08428f96fda..8bea4ef30ac 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -7,7 +7,7 @@ Status: Active Type: Process Content-Type: text/x-rst Created: 05-Aug-2002 -Post-History: `30-Aug-2002 `_ +Post-History: `30-Aug-2002 `__ .. note:: @@ -123,14 +123,14 @@ directions below. to this header each time you post your PEP to the designated discussion forum (and update the ``Discussions-To`` header with said link, as above). If you posted threads for your PEP on August 14, 2001 and September 3, 2001, - the Post-History header would look something like: + the Post-History header would look like, e.g.: .. code-block:: email - Post-History: `14-Aug-2001 `_, - `03-Sept-2001 `_ + Post-History: `14-Aug-2001 `__, + `03-Sept-2001 `__ - You must manually add new dates/links as soon as you post a + You should add the new dates/links here as soon as you post a new discussion thread. - Add a Replaces header if your PEP obsoletes an earlier PEP. The @@ -173,7 +173,7 @@ your PEP): Requires: *[NNN] Created: [DD-MMM-YYYY] Python-Version: *[M.N] - Post-History: [`DD-MMM-YYYY `_] + Post-History: [`DD-MMM-YYYY `__] Replaces: *[NNN] Superseded-By: *[NNN] Resolution: From ceec06081300e91833ba22d3f6dc8f2cb64d081d Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 7 Mar 2022 21:15:54 -0600 Subject: [PATCH 4/4] PEP 1 & 12: More explictly describe Post-History link format --- pep-0001.txt | 2 +- pep-0012.rst | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index f6caf0ffcdb..94d116ca211 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -660,7 +660,7 @@ The Created header records the date that the PEP was assigned a number, while Post-History is used to record the dates of and corresponding URLs to the Discussions-To threads for the PEP, with the former as the linked text, and the latter as the link target. -Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001. +Both sets of dates should be in ``dd-mmm-yyyy`` format, e.g. ``14-Aug-2001``. Standards Track PEPs will typically have a Python-Version header which indicates the version of Python that the feature will be released with. diff --git a/pep-0012.rst b/pep-0012.rst index 8bea4ef30ac..2ba7e22ae2f 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -121,7 +121,11 @@ directions below. - Leave Post-History alone for now; you'll add dates and corresponding links to this header each time you post your PEP to the designated discussion forum - (and update the ``Discussions-To`` header with said link, as above). + (and update the Discussions-To header with said link, as above). + For each thread, use the date (in the ``dd-mmm-yyy`` format) as the + linked text, and insert the URLs inline as anonymous reST `hyperlinks`_, + with commas in between each posting. + If you posted threads for your PEP on August 14, 2001 and September 3, 2001, the Post-History header would look like, e.g.: