From e413ea93b1205fd408d8bc785315401d16ef2d10 Mon Sep 17 00:00:00 2001 From: Eli Bendersky Date: Wed, 29 Feb 2012 21:44:39 +0200 Subject: [PATCH] PEP 411: incorporated comments from pydev discussions --- pep-0411.txt | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/pep-0411.txt b/pep-0411.txt index ccf87c09d..02ca5706f 100644 --- a/pep-0411.txt +++ b/pep-0411.txt @@ -39,10 +39,10 @@ package's API is optimal, the package can be included and marked as "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 @@ of provisional packages. 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 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