Update PEP 387 based on discussions (#1432)

pep-0387.txt

@@ -4,11 +4,12 @@ Version: $Revision$
 Last-Modified: $Date$
 Author: Benjamin Peterson <benjamin@python.org>
 BDFL-Delegate: Brett Cannon (on behalf of the steering council)
+Discussions-To: https://discuss.python.org/t/pep-387-backwards-compatibilty-policy/
 Status: Draft
 Type: Process
 Content-Type: text/x-rst
 Created: 18-Jun-2009
-Post-History: 19-Jun-2009
+Post-History: 19-Jun-2009, 12-Jun-2020
 
 
 Abstract
@@ -33,9 +34,9 @@ Backwards Compatibility Rules
 This policy applies to all public APIs.  These include:
 
 - Syntax and behavior of these constructs as defined by the reference
-  manual
+  manual.
 
-- The C-API
+- The C-API.
 
 - Function, class, module, attribute, and method names and types.
 
@@ -48,31 +49,44 @@ This policy applies to all public APIs.  These include:
 - Behavior of classes with regards to subclasses: the conditions under
   which overridden methods are called.
 
+- Documented exceptions and the semantics which lead to their raising.
+
+- Exceptions commonly raised in EAFP scenarios.
+
 Others are explicitly not part of the public API.  They can change or
 be removed at any time in any way.  These include:
 
-- Function, class, module, attribute, method, and C-API names and types that
+- Function, class, module, attribute, method, and C-API names and
-  are prefixed by "_" (except special names).  The contents of these
+  types that are prefixed by "_" (except special names).
-  are also not subject to the policy.
+
+- Anything documented publicly as being private.
+
+- Imported modules (unless explicitly documented as part of the public
+  API; e.g. importing the ``bacon`` module in the ``spam`` does not
+  automatically mean ``spam.bacon`` is part of hte public API unless
+  it is documented as such).
 
 - Inheritance patterns of internal classes.
 
-- Test suites.  (Anything in the Lib/test directory or test
+- Test suites.  (Anything in the ``Lib/test`` directory or test
   subdirectories of packages.)
 
-This is the basic policy for backwards compatibility:
+
+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
+  name as a third party package is generally not acceptable.  Adding
-  attribute that conflicts with 3rd party code through inheritance,
+  a method or attribute that conflicts with 3rd party code through
-  however, is likely reasonable.
+  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
+  behavior of an API *must* not change in an incompatible fashion
-  releases. Python's yearly release process (:pep:`602`) means that
+  between any two consecutive releases.  Python's yearly release
-  the deprecation period must last at least two years.
+  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.
@@ -88,8 +102,8 @@ This is the basic policy for backwards compatibility:
 Making Incompatible Changes
 ===========================
 
-Making an incompatible change is a gradual process performed over several
+Making an incompatible change is a gradual process performed over
-releases:
+several releases:
 
 1. Discuss the change.  Depending on the degree of incompatibility,
    this could be on the bug tracker, python-dev, python-list, or the
@@ -114,7 +128,8 @@ releases:
    reconsider.
 
 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.
+   permanent having reached the declared version. Remove the old
+   version and warning.
 
 
 References