http://hg.python.org/peps/rev/78b0a17b50ac changeset: 4101:78b0a17b50ac user: Eli Bendersky <eliben@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