PEP: 387 Title: Backwards Compatibility Policy Version: $Revision$ Last-Modified: $Date$ Author: Benjamin Peterson Status: Draft Type: Process Content-Type: text/x-rst Created: 18-Jun-2009 Abstract ======== 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 critcal role in thousands of applications and libraries. This is fantastic; it is probably one of a language designer's most wishful dreams. However, it means the development team must be very careful not to break this existing 3rd party code with new releases. Backwards Compatibility Rules ============================= This policy applys to all public APIs. These include the C-API, the standard library, and the core language including syntax and operation as defined by the reference manual. This is the basic policy for backwards compatibility: * The behavior of an API *must* not change between any two consecutive releases. * 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. 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: 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. 2. Add a warning [#warnings]_. If behavior is changing, a 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. 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. References ========== .. [#tiobe] TIOBE Programming Community Index http://www.tiobe.com/index.php/content/paperinfo/tpci/index.html .. [#warnings] The warnings module http://docs.python.org/library/warnings.html Copyright ========= This document has been placed in the public domain. .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 coding: utf-8 End: