[Python-checkins] r73475 - peps/trunk/pep-0387.txt

Fri Jun 19 04:18:28 CEST 2009

Author: benjamin.peterson
Date: Fri Jun 19 04:18:28 2009
New Revision: 73475
Log:
bite the bullet: a draft backwards compat policy
Added:
 peps/trunk/pep-0387.txt (contents, props changed)
Added: peps/trunk/pep-0387.txt
==============================================================================

--- (empty file)
+++ peps/trunk/pep-0387.txt	Fri Jun 19 04:18:28 2009
@@ -0,0 +1,101 @@
+PEP: 387
+Title: Backwards Compatibility Policy
+Version: $Revision$
+Last-Modified: $Date$
+Author: Benjamin Peterson <benjamin at python.org>
+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:
