diff --git a/pep-0387.txt b/pep-0387.txt index ca2667e43..f21a337fb 100644 --- a/pep-0387.txt +++ b/pep-0387.txt @@ -4,11 +4,12 @@ Version: $Revision$ Last-Modified: $Date$ Author: Benjamin Peterson 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 - are prefixed by "_" (except special names). The contents of these - are also not subject to the policy. +- Function, class, module, attribute, method, and C-API names and + types that are prefixed by "_" (except special names). + +- 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 - attribute that conflicts with 3rd party code through inheritance, - however, is likely reasonable. + name as a third party package is generally 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. Python's yearly release process (:pep:`602`) means that - the deprecation period must last at least two years. + behavior of an API *must* not change in an incompatible fashion + between any two consecutive 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. @@ -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 -releases: +Making an incompatible change is a gradual process performed over +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