[Python-checkins] peps: PEP 411: incorporated comments from pydev discussions

[eli.bendersky]

http://hg.python.org/peps/rev/78b0a17b50ac
changeset:   4101:78b0a17b50ac
user:        Eli Bendersky <eliben at gmail.com>
date:        Wed Feb 29 21:44:39 2012 +0200
summary:
  PEP 411: incorporated comments from pydev discussions

files:
  pep-0411.txt |  44 ++++++++++++++++++++++++++++-----------
  1 files changed, 31 insertions(+), 13 deletions(-)


diff --git a/pep-0411.txt b/pep-0411.txt
--- a/pep-0411.txt
+++ b/pep-0411.txt
@@ -39,10 +39,10 @@
 "provisional".
 
 In the next minor release, the package may either be "graduated" into a normal
-"stable" state in the standard library, or be rejected and removed entirely
-from the Python source tree.  If the package ends up graduating into the
-stable state after being provisional for a minor release, its API may be
-changed according to accumulated feedback.  The core development team
+"stable" state in the standard library, remain in provisional state, or be
+rejected and removed entirely from the Python source tree.  If the package ends
+up graduating into the stable state after being provisional, its API may 
+be changed according to accumulated feedback.  The core development team
 explicitly makes no guarantees about API stability and backward compatibility
 of provisional packages.
 
@@ -50,19 +50,37 @@
 Marking a package provisional
 -----------------------------
 
-A package will be marked provisional by including the following paragraph as
-a note at the top of its documentation page:
+A package will be marked provisional by a notice in its documentation page and
+its docstring. The following paragraph will be added as a note at the top of
+the documentation page:
 
     The <X> package has been included in the standard library on a
-    provisional basis. While major changes are not anticipated, as long as
-    this notice remains in place, backwards incompatible changes are
-    permitted if deemed necessary by the standard library developers. Such
-    changes will not be made gratuitously - they will occur only if
-    serious API flaws are uncovered that were missed prior to inclusion of
-    the package.
+    provisional basis.  Backwards incompatible changes (up to and including
+    removal of the package) may occur if deemed necessary by the core
+    developers.
+
+The phrase "provisional basis" will then be a link to the glossary term
+"provisional package", defined as:
+
+    A provisional package is one which has been deliberately excluded from the
+    standard library's normal backwards compatibility guarantees.  While major
+    changes to such packages are not expected, as long as they are marked 
+    provisional, backwards incompatible changes (up to and including removal of
+    the package) may occur if deemed necessary by core developers.  Such changes
+    will not be made gratuitously - they will occur only if serious flaws are
+    uncovered that were missed prior to the inclusion of the package.
+
+    This process allows the standard library to continue to evolve over time,
+    without locking in problematic design errors for extended periods of time.
+    See PEP 411 for more details.
+
+The following will be added to the start of the packages's docstring:
+
+    The API of this package is currently provisional.  Refer to the
+    documentation for details.
 
 Moving a package from the provisional to the stable state simply implies
-removing this note from its documentation page.
+removing these notes from its documentation page and docstring.
 
 
 Which packages should go through the provisional state

-- 
Repository URL: http://hg.python.org/peps