bite the bullet: a draft backwards compat policy

pep-0387.txt

@@ -0,0 +1,101 @@
+PEP: 387
+Title: Backwards Compatibility Policy
+Version: $Revision$
+Last-Modified: $Date$
+Author: Benjamin Peterson <benjamin@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: