PEP 1: Add a separate "Provisional" PEP status (#577)

This adds an explicit "Provisional" status for PEPs, making
it easier to track which PEPs are truly Final, and which
are pending further further public feedback based on
their initially published reference implementations.

Author: ncoghlan

pep-0001-1.png

@@ -245,7 +245,22 @@ Once a PEP has been accepted, the reference implementation must be
 completed.  When the reference implementation is complete and incorporated
 into the main source code repository, the status will be changed to "Final".
 
-A PEP can also be assigned status "Deferred".  The PEP author or an
+To allow gathering of additional design and interface feedback before committing
+to long term stability for a language feature or standard library API, a PEP
+may also be marked as "Provisional". This is short for "Provisionally Accepted",
+and indicates that the proposal has been accepted for inclusion in the reference
+implementation, but additional user feedback is needed before the full design
+can be considered "Final". Unlike regular accepted PEPs, provisionally accepted
+PEPs may still be Rejected or Withdrawn *even after the related changes have
+been included in a Python release*.
+
+Wherever possible, it is considered preferable to reduce the scope of a proposal
+to avoid the need to rely on the "Provisional" status (e.g. by deferring some
+features to later PEPs), as this status can lead to version compatibility
+challenges in the wider Python ecosystem. PEP 411 provides additional details
+on potential use cases for the Provisional status.
+
+A PEP can also be assigned the status "Deferred".  The PEP author or an
 editor can assign the PEP this status when no progress is being made
 on the PEP.  Once a PEP is deferred, a PEP editor can re-assign it
 to draft status.
@@ -267,7 +282,16 @@ an API can replace version 1.
 
 The possible paths of the status of PEPs are as follows:
 
-.. image:: pep-0001-1.png
+.. image:: pep-0001-1.svg
+
+While not shown in the diagram, "Accepted" PEPs may technically move to
+"Rejected" or "Withdrawn" even after acceptance. This will only occur if
+the implementation process reveals fundamental flaws in the design that were
+not noticed prior to acceptance of the PEP. Unlike Provisional PEPs, these
+transitions are only permitted if the accepted proposal has *not* been included
+in a Python release - released changes must instead go through the regular
+deprecation process (which may require a new PEP providing the rationale for
+the deprecation).
 
 Some Informational and Process PEPs may also have a status of "Active"
 if they are never meant to be completed.  E.g. PEP 1 (this PEP).
@@ -281,6 +305,11 @@ reached the Final state. Once a PEP has been completed, the Language and
 Standard Library References become the formal documentation of the expected
 behavior.
 
+If changes based on implementation experience and user feedback are made to
+Standards track PEPs while in the Accepted or Provisional State, those changes
+should be noted in the PEP, such that the PEP accurately describes the state of
+the implementation at the point where it is marked Final.
+
 Informational and Process PEPs may be updated over time to reflect changes
 to development practices and other details. The precise process followed in
 these cases will depend on the nature and purpose of the PEP being updated.
@@ -379,7 +408,7 @@ optional and are described below.  All other headers are required. ::
     Author: <list of authors' real names and optionally, email addrs>
   * BDFL-Delegate: <PEP czar's real name>
   * Discussions-To: <email address>
-    Status: <Draft | Active | Accepted | Deferred | Rejected |
+    Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
              Withdrawn | Final | Superseded>
     Type: <Standards Track | Informational | Process>
   * Content-Type: <text/x-rst | text/plain>

pep-0001-1.svg

@@ -5,7 +5,7 @@ Last-Modified: $Date$
 Author: Guido van Rossum <[email protected]>, Jukka Lehtosalo <[email protected]>, Łukasz Langa <[email protected]>
 BDFL-Delegate: Mark Shannon
 Discussions-To: Python-Dev <[email protected]>
-Status: Accepted
+Status: Provisional
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 29-Sep-2014

pep-0001.txt

@@ -6,7 +6,7 @@ Author: Nathaniel J. Smith <[email protected]>,
         Thomas Kluyver <[email protected]>
 BDFL-Delegate: Nick Coghlan <[email protected]>
 Discussions-To: <[email protected]>
-Status: Accepted
+Status: Provisional
 Type: Standards Track
 Content-Type: text/x-rst
 Created: 30-Sep-2015

pep-0484.txt

@@ -7,8 +7,8 @@ Author: Brett Cannon <[email protected]>,
         Donald Stufft <[email protected]>
 BDFL-Delegate: Nick Coghlan
 Discussions-To: distutils-sig <distutils-sig at python.org>
-Status: Accepted
-Type: Informational
+Status: Provisional
+Type: Standards Track
 Content-Type: text/x-rst
 Created: 10-May-2016
 Post-History: 10-May-2016,

pep-0517.txt

@@ -42,6 +42,7 @@ def sort_peps(peps):
     and essentially dead."""
     meta = []
     info = []
+    provisional = []
     accepted = []
     open_ = []
     finished = []
@@ -74,6 +75,8 @@ def sort_peps(peps):
                 info.append(pep)
             else:
                 historical.append(pep)
+        elif pep.status == 'Provisional':
+            provisional.append(pep)
         elif pep.status in ('Accepted', 'Active'):
             accepted.append(pep)
         elif pep.status == 'Final':
@@ -82,7 +85,8 @@ def sort_peps(peps):
             raise PEPError("unsorted (%s/%s)" %
                            (pep.type_, pep.status),
                            pep.filename, pep.number)
-    return meta, info, accepted, open_, finished, historical, deferred, dead
+    return (meta, info, provisional, accepted, open_,
+            finished, historical, deferred, dead)
 
 
 def verify_email_addresses(peps):
@@ -140,8 +144,8 @@ def write_pep0(peps, output=sys.stdout):
     print(u"Index by Category", file=output)
     print(file=output)
     write_column_headers(output)
-    (meta, info, accepted, open_, finished,
-           historical, deferred, dead) = sort_peps(peps)
+    (meta, info, provisional, accepted, open_,
+           finished, historical, deferred, dead) = sort_peps(peps)
     print(file=output)
     print(u" Meta-PEPs (PEPs about PEPs or Processes)", file=output)
     print(file=output)
@@ -153,6 +157,12 @@ def write_pep0(peps, output=sys.stdout):
     for pep in info:
         print(constants.text_type(pep), file=output)
     print(file=output)
+    print(u" Provisional PEPs (provisionally accepted; interface may still change)",
+          file=output)
+    print(file=output)
+    for pep in provisional:
+        print(constants.text_type(pep), file=output)
+    print(file=output)
     print(u" Accepted PEPs (accepted; may not be implemented yet)", file=output)
     print(file=output)
     for pep in accepted:
@@ -163,7 +173,7 @@ def write_pep0(peps, output=sys.stdout):
     for pep in open_:
         print(constants.text_type(pep), file=output)
     print(file=output)
-    print(u" Finished PEPs (done, implemented in code repository)", file=output)
+    print(u" Finished PEPs (done, with a stable interface)", file=output)
     print(file=output)
     for pep in finished:
         print(constants.text_type(pep), file=output)

pep-0518.txt

@@ -169,7 +169,8 @@ class PEP(object):
     type_values = (u"Standards Track", u"Informational", u"Process")
     # Valid values for the Status header.
     # Active PEPs can only be for Informational or Process PEPs.
-    status_values = (u"Accepted", u"Rejected", u"Withdrawn", u"Deferred",
+    status_values = (u"Accepted", u"Provisional",
+                     u"Rejected", u"Withdrawn", u"Deferred",
                      u"Final", u"Active", u"Draft", u"Superseded")
 
     def __init__(self, pep_file):
@@ -229,6 +230,11 @@ def __init__(self, pep_file):
             raise PEPError("Only Process and Informational PEPs may "
                            "have an Active status", pep_file.name,
                            self.number)
+        # Special case for Provisional PEPs.
+        if (status == u"Provisional" and self.type_ != "Standards Track"):
+            raise PEPError("Only Standards Track PEPs may "
+                           "have a Provisional status", pep_file.name,
+                           self.number)
         self.status = status
         # 'Author'.
         authors_and_emails = self._parse_author(metadata['Author'])