PEP 1 & 12: Link Post-History dates to discussion threads (#2358)

Author: CAM-Gerlach

pep-0001.txt

@@ -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: <pep numbers>
     Created: <date created on, in dd-mmm-yyyy format>
   * Python-Version: <version number>
-    Post-History: <dates of postings to Python-Dev and/or the Discussions-To thread, in dd-mmm-yyyy format>
+    Post-History: <dates, in dd-mmm-yyyy format,
+                   inline-linked to PEP discussion threads>
   * Replaces: <pep number>
   * Superseded-By: <pep number>
   * Resolution: <url>
@@ -654,9 +655,10 @@ and have a value of ``text/x-rst``, the default.
 Previously, plaintext PEPs used ``text/plain`` (see :pep:`9`).
 
 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.
-Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
+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 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.

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 <https://mail.python.org/archives/list/[email protected]/thread/KX3AS7QAY26QH3WIUAEOCCNXQ4V2TGGV/>`__
 
 
 .. note::
@@ -113,20 +113,29 @@ 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).
+  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::
+  the Post-History header would look like, e.g.:
 
-      Post-History: 14-Aug-2001, 03-Sept-2001
+  .. code-block:: email
 
-  You must manually add new dates and commit them (with a pull request
-  if you don't have push privileges).
+      Post-History: `14-Aug-2001 <https://www.example.com/thread_1>`__,
+                    `03-Sept-2001 <https://www.example.com/thread_2>`__
+
+  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
   value of this header is the number of the PEP that your new PEP is
@@ -149,7 +158,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: [...]
@@ -163,7 +174,7 @@ your PEP)::
   Requires: *[NNN]
   Created: [DD-MMM-YYYY]
   Python-Version: *[M.N]
-  Post-History: [DD-MMM-YYYY]
+  Post-History: [`DD-MMM-YYYY <URL>`__]
   Replaces: *[NNN]
   Superseded-By: *[NNN]
   Resolution:

pep-0012/pep-NNNN.rst

@@ -10,7 +10,7 @@ Content-Type: text/x-rst
 Requires: <pep numbers>
 Created: <date created on, in dd-mmm-yyyy format>
 Python-Version: <version number>
-Post-History: <REQUIRED: dates of postings to Python-Dev and/or the Discussions-To thread, in dd-mmm-yyyy format>
+Post-History: <REQUIRED: dates, in dd-mmm-yyyy format, and corresponding links to PEP discussion threads>
 Replaces: <pep number>
 Superseded-By: <pep number>
 Resolution: <url>