Lots of PEP 387 updates.

pep-0387.txt

@@ -20,11 +20,11 @@ This PEP outlines Python's backwards compatibility policy.
 Rationale
 =========
 
-As one of the most used programming languages today [#tiobe]_, the Python core
-language and its standard library play a critical role in millions of
-applications and libraries. This is fantastic. However, it means the development
-team must be very careful not to break this existing 3rd party code with new
-releases.
+As one of the most used programming languages today [#tiobe]_, the
+Python core language and its standard library play a critical role in
+millions of applications and libraries. This is fantastic. However, it
+means the development team must be very careful not to break this
+existing 3rd party code with new releases.
 
 
 Backwards Compatibility Rules
@@ -62,47 +62,57 @@ be removed at any time in any way.  These include:
 
 This is the basic policy for backwards compatibility:
 
+* In general, incompatibilities should have a large benefit to
+  breakage ratio, and the incompatibility should be easy to resolve in
+  affected code.  For example, adding an stdlib module with the same
+  name as a third party package is not acceptable.  Adding a method or
+  attribute that conflicts with 3rd party code through inheritance,
+  however, is likely reasonable.
+
 * Unless it is going through the deprecation process below, the
   behavior of an API *must* not change between any two consecutive
-  releases.
+  releases. Python's yearly release process (:pep:`602`) means that
+  the deprecation period must last at least two years.
 
 * Similarly a feature cannot be removed without notice between any two
   consecutive releases.
 
-* Addition of a feature which breaks 3rd party libraries or applications should
-  have a large benefit to breakage ratio, and/or the incompatibility should be
-  trival to fix in broken code.  For example, adding an stdlib module
-  with the same name as a third party package is not acceptable.
-  Adding a method or attribute that conflicts with 3rd party code
-  through inheritance, however, is likely reasonable.
+* The steering council may grant exceptions to this policy. In
+  particular, they may shorten the required deprecation period for a
+  feature. Exceptions are only granted for extreme situations such as
+  dangerously broken or insecure features or features no one could
+  reasonably be depending on (e.g., support for completely obsolete
+  platforms).
 
 
 Making Incompatible Changes
 ===========================
 
-It's a fact: design mistakes happen.  Thus it is important to be able to change
-APIs or remove misguided features.  This is accomplished through a gradual
-process over several releases:
+Making an incompatible change is a gradual process performed over several
+releases:
 
-1. Discuss the change.  Depending on the size of the incompatibility, this could
-   be on the bug tracker, python-dev, python-list, or the appropriate SIG.  A
-   PEP or similar document may be written.  Hopefully users of the affected API
-   will pipe up to comment.
+1. Discuss the change.  Depending on the degree of incompatibility,
+   this could be on the bug tracker, python-dev, python-list, or the
+   appropriate SIG.  A PEP or similar document may be written.
+   Hopefully users of the affected API will pipe up to comment.
 
-2. Add a warning [#warnings]_.  If behavior is changing, the API may gain a
-   new function or method to perform the new behavior; old usage should raise
-   the warning.  If an API is being removed, simply warn whenever it is entered.
-   DeprecationWarning is the usual warning category to use, but
-   PendingDeprecationWarning may be used in special cases were the old and new
-   versions of the API will coexist for many releases.
+2. Add a warning [#warnings]_.  If behavior is changing, the API may
+   gain a new function or method to perform the new behavior; old
+   usage should raise the warning.  If an API is being removed, simply
+   warn whenever it is entered.  ``DeprecationWarning`` is the usual
+   warning category to use, but ``PendingDeprecationWarning`` may be
+   used in special cases were the old and new versions of the API will
+   coexist for many releases.
 
-3. Wait for a release of whichever branch contains the warning.
+3. Wait for the warning to appear in at least two major Python
+   versions. It's fine to wait more than two releases.
 
-4. See if there's any feedback.  Users not involved in the original discussions
-   may comment now after seeing the warning.  Perhaps reconsider.
+4. See if there's any feedback.  Users not involved in the original
+   discussions may comment now after seeing the warning.  Perhaps
+   reconsider.
 
-5. The behavior change or feature removal may now be made default or permanent
-   in the next release.  Remove the old version and warning.
+5. The behavior change or feature removal may now be made default or
+   permanent in the N+3 release.  Remove the old version and warning.
 
 
 References