[Python-Dev] Gradual migration PEP
Thu, 26 Oct 2000 07:28:12 -0700
Title: Guidelines for introducing backwards incompatibilities
Version: $Revision: 1.0 $
Author: Paul Prescod <firstname.lastname@example.org,email@example.com>
Status: Draft Type: Standards Track
In the natural evolution of programming languages it is sometimes
necessary to make changes that modify the behaviour of older
This PEP proposes a policy for implementing these changes in a
respectful of the installed base of Python users.
Implementation of this PEP requires the addition of a formal warning
and deprecation facility that will be described in another proposal.
These guidelines apply to future versions of Python that introduce
backward-incompatible behaviour. Backward incompatible behaviour is
a major deviation in Python interpretation from an earlier behaviour
described in the standard Python documentation. Removal of a feature
also constitutes a change of behaviour.
This PEP does not replace or preclude other compatibility strategies
such as dynamic loading of backwards-compatible parsers. On the
other hand, if execution of "old code" requires a special switch or
pragma then that is indeed a change of behavior from the point of
view of the user and that change should be implemented according to
In general, common sense must prevail in the implementation of these
guidelines. For instance changing "sys.copyright" does not
a backwards-incompatible change of behavior!
Steps For Introducting Backwards-Incompatible Features
1. Propose backwards-incompatible behavior in a PEP. The PEP must
include a section on backwards compatibility that describes in
detail a plan to complete the remainder of these steps.
2. Once the PEP is accepted as a productive direction, implement an
alternate way to accomplish the task previously provided by the
feature that is being removed or changed. For instance if the
addition operator were scheduled for removal, a new version of
Python could implement an "add()" built-in function.
3. Formally deprecate the obsolete construct in the Python
4. Add an an optional warning mode to the parser that will inform
users when the deprecated construct is used. In other words, all
programs that will behave differently in the future must trigger
warnings in this mode. Compile-time warnings are preferable to
runtime warnings. The warning messages should steer people from
the deprecated construct to the alternative construct.
5. There must be at least a one-year transition period between
the release of the transitional version of Python and the release
of the backwards incompatible version. Users will have at least
a year to test their programs and migrate them from use of the
deprecated construct to the alternative one.