This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add the policy on compatibility and deprecation to perlpolicy.pod,
authorJesse Vincent <jesse@bestpractical.com>
Mon, 28 Jun 2010 23:16:21 +0000 (19:16 -0400)
committerJesse Vincent <jesse@bestpractical.com>
Tue, 29 Jun 2010 02:30:04 +0000 (22:30 -0400)
aloing with definitions of terms like "deprecation"

pod/perlpolicy.pod

index 380a177..d9a0642 100644 (file)
@@ -8,6 +8,111 @@ This document is the master document which records all written
 policies about how the Perl 5 Porters collectively develop and maintain
 the Perl core.
 
+=head1 BACKWARD COMPATIBILITY AND DEPRECATION
+
+Our community has a long-held belief that backward-compatibility is a
+virtue, even when the functionality in question is a design flaw.
+
+We would all love to unmake some mistakes we've made over the past
+decades.  Living with every design error we've ever made can lead
+to painful stagnation.  Unwinding our mistakes is very, very
+difficult.  Doing so without actively harming our users is
+nearly impossible.
+
+Lately, ignoring or actively opposing compatibility with earlier versions
+of Perl has come into vogue.  Sometimes, a change is proposed which
+wants to usurp syntax which previously had another meaning.  Sometimes,
+a change wants to improve previously-crazy semantics.
+
+Down this road lies madness.
+
+Requiring end-user programmers to change just a few language constructs,
+even language constructs which no well-educated developer would ever
+intentionally use is tantamount to saying "you should not upgrade to
+a new release of Perl unless you have 100% test coverage and can do a
+full manual audit of your codebase."  If we were to have tools capable of
+reliably upgrading Perl source code from one version of Perl to another,
+this concern could be significantly mitigated.
+
+We want to ensure that Perl continues to grow and flourish in the coming
+years and decades, but not at the expense of our user community.
+
+Existing syntax and semantics should only be marked for destruction in
+very limited circumstances.  If a given language feature's continued
+inclusion in the language will cause significant harm to the language
+or prevent us from making needed changes to the runtime, then it may
+be considered for deprecation.
+
+Any language change which breaks backward-compatibility should be able to
+be enabled or disabled lexically.  Unless code at a given scope declares
+that it wants the new behavior, that new behavior should be disabled.
+Which backward-incompatible changes are controlled implicitly by a
+'use v5.x.y' is a decision which should be made by the pumpking in
+consultation with the community.
+
+When a backward-incompatible change can't be toggled lexically, the decision
+to change the language must be considered very, very carefully.  If it's
+possible to move the old syntax or semantics out of the core language
+and into XS-land, that XS module should be enabled by default unless
+the user declares that they want a newer revision of Perl.
+
+Historically, we've held ourselves to a far higher standard than
+backward-compatibility -- bugward-compatibility.  Any accident of
+implementation or unintentional side-effect of running some bit of code
+has been considered to be a feature of the language to be defended with
+the same zeal as any other feature or functionality.  No matter how
+frustrating these unintentional features may be to us as we continue
+to improve Perl, these unintentional features often deserve our
+protection.  It is very important that existing software written in
+Perl continue to work correctly.  If end-user developers have adopted a
+bug as a feature, we need to treat it as such.
+
+New syntax and semantics which don't break existing language constructs
+and syntax have a much lower bar.  They merely need to prove themselves
+to be useful, elegant, well designed and well tested.
+
+=head2 Terminology
+
+To make sure we're talking about the same thing when we discuss the removal
+of features or functionality from the Perl core, we have specific definitions
+for a few words and phrases.
+
+=over
+
+=item experimental
+
+If something in the Perl core is marked as B<experimental>, we may change
+its behaviour, deprecate or remove it without notice. While we'll always
+do our best to smooth the transition path for users of experimental
+features, you should contact the perl5-porters mailinglist if you find
+an experimental feature useful and want to help shape its future.
+
+=item deprecated
+
+If something in the Perl core is marked as B<deprecated>, we may remove it
+from thecore in the next stable release series, though we may not. As of
+Perl 5.12, deprecated features and modules warn the user as they're used.
+If you use a deprecated feature and believe that its removal from the Perl
+core would be a mistake, please contact the perl5-porters mailinglist and
+plead your case.  We don't deprecate things without a good reason, but
+sometimes there's a counterargument we haven't considered.  Historically,
+we did not distinguish between "deprecated" and "discouraged" features.
+
+=item discouraged
+
+From time to time, we may mark language constructs and features which we
+consider to have been mistakes as B<discouraged>.  Discouraged features
+aren't candidates for removal in the next major release series, but
+we may later deprecate them if they're found to stand in the way of a
+significant improvement to the core.
+
+=item removed
+
+Once a feature, construct or module has been marked as deprecated for a
+stable release cycle, we may remove it from the core.  Unsurprisingly,
+we say we've B<removed> these things.
+
+=back
 
 =head1 MAINTENANCE BRANCHES
 
@@ -200,6 +305,7 @@ at a compromise.  In nearly every circumstance nothing more will be
 necessary, and certainly no more drastic measure should be used until
 every avenue of communication and discussion has failed.
 
+
 =head1 CREDITS
 
 Social Contract about Contributed Modules originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters.