This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfaq is not the only exception; just say "few"
[perl5.git] / pod / perlpolicy.pod
index 5f61e2f..a36e1e0 100644 (file)
@@ -8,7 +8,256 @@ 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 MAINTENANCE AND SUPPORT
 
+Perl 5 is developed by a community, not a corporate entity. Every change
+contributed to the Perl core is the result of a donation. Typically, these
+donations are contributions of code or time by individual members of our
+community. On occasion, these donations come in the form of corporate
+or organizational sponsorship of a particular individual or project.
+
+As a volunteer organization, the commitments we make are heavily dependent
+on the goodwill and hard work of individuals who have no obligation to
+contribute to Perl.
+
+That being said, we value Perl's stability and security and have long
+had an unwritten covenant with the broader Perl community to support
+and maintain releases of Perl.
+
+This document codifies the support and maintenance commitments that
+the Perl community should expect from Perl's developers:
+
+=over
+
+=item *
+
+We "officially" support the two most recent stable release
+series'.  As of the release of 5.14.0, we will "officially"
+end support for Perl 5.10, other than providing security
+updates as described below.
+
+=item *
+
+To the best of our ability, we will attempt to fix critical issues
+in the two most recent stable 5.x release series'.  Fixes for the
+current release series take precedence over fixes for the previous
+release series.
+
+=item *
+
+To the best of our ability, we will provide "critical" security patches
+/ releases for any major version of Perl initially released within the
+past three years.  We can only commit to providing these for the most
+recent .y release in any 5.x.y series.
+
+=item *
+
+We will not provide security updates or bug fixes for development
+releases of Perl.
+
+=item *
+
+We encourage vendors to ship the most recent supported release of
+Perl at the time of their code freeze.
+
+=item *
+
+As a vendor, you may have a requirement to backport security fixes
+beyond our 3 year support commitment.  We can provide limited support and
+advice to you as you do so and, where possible will try to apply
+those patches to the relevant -maint branches in git, though we may or
+may not choose to make numbered releases or "official" patches
+available.  Contact us at E<lt>perl5-security-report@perl.orgE<gt>
+to begin that process.
+
+=back
+
+=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 the core 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
+
+=over
+
+=item *
+
+New releases of maint should contain as few changes as possible.
+If there is any question about whether a given patch might merit
+inclusion in a maint release, then it almost certainly should not
+be included.
+
+=item *
+
+Portability fixes, such as changes to Configure and the files in
+hints/ are acceptable. Ports of Perl to a new platform, architecture
+or OS release that involve changes to the implementation are NOT
+acceptable.
+
+=item *
+
+Documentation updates are acceptable.
+
+=item *
+
+Patches that add new warnings or errors or deprecate features
+are not acceptable.
+
+=item *
+
+Patches that fix crashing bugs that do not otherwise change Perl's
+functionality or negatively impact performance are acceptable.  
+
+=item *
+
+Patches that fix CVEs or security issues are acceptable, but should
+be run through the perl5-security-report@perl.org mailing list
+rather than applied directly.
+
+=item *
+
+Updates to dual-life modules should consist of minimal patches to 
+fix crashing or security issues (as above).
+
+=item *
+
+Minimal patches that fix platform-specific test failures or
+installation issues are acceptable. When these changes are made
+to dual-life modules for which CPAN is canonical, any changes
+should be coordinated with the upstream author.
+
+=item *
+
+New versions of dual-life modules should NOT be imported into maint.
+Those belong in the next stable series.
+
+=item *
+
+Patches that add or remove features are not acceptable.
+
+=item *
+
+Patches that break binary compatibility are not acceptable.  (Please
+talk to a pumpking.)
+
+=back
+
+
+=head2 Getting changes into a maint branch
+
+Historically, only the pumpking cherry-picked changes from bleadperl
+into maintperl.  This has...scaling problems.  At the same time,
+maintenance branches of stable versions of Perl need to be treated with
+great care. To that end, we're going to try out a new process for
+maint-5.12.
+
+Any committer may cherry-pick any commit from blead to maint-5.12 if
+they send mail to perl5-porters announcing their intent to cherry-pick
+a specific commit along with a rationale for doing so and at least two 
+other committers respond to the list giving their assent. (This policy
+applies to current and former pumpkings, as well as other committers.)
 
 =head1 CONTRIBUTED MODULES
 
@@ -50,10 +299,12 @@ gives up their ownership of it.  In particular:
 
 =over
 
-=item *  The version of the module in the core should still be considered the
-    work of the original author.  All patches, bug reports, and so forth
-    should be fed back to them.  Their development directions should be
-    respected whenever possible.
+=item *
+
+The version of the module in the core should still be considered the
+work of the original author.  All patches, bug reports, and so
+forth should be fed back to them.  Their development directions
+should be respected whenever possible.
 
 =item *
 
@@ -125,7 +376,46 @@ 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 DOCUMENTATION
+
+Perl's documentation is an important resource for our users. It's
+incredibly important for Perl's documentation to be reasonably coherent
+and to accurately reflect the current implementation.
+
+Just as P5P collectively maintains the codebase, we collectively
+maintain the documentation.  Writing a particular bit of documentation
+doesn't give an author control of the future of that documentation.
+At the same time, just as source code changes should match the style
+of their surrounding blocks, so should documentation changes.
+
+Examples in documentation should be illustrative of the concept
+they're explaining.  Sometimes, the best way to show how a
+language feature works is with a small program the reader can
+run without modification.  More often, examples will consist
+of a snippet of code containing only the "important" bits.
+The definition of "important" varies from snippet to snippet.
+Sometimes it's important to declare C<use strict> and C<use warnings>,
+initialize all variables and fully catch every error condition.
+More often than not, though, those things obscure the lesson
+the example was intended to teach.
+
+As Perl is developed by a global team of volunteers, our
+documentation often contains spellings which look funny
+to I<somebody>.  Choice of American/British/Other spellings
+is left as an exercise for the author of each bit of
+documentation.  When patching documentation, try to emulate
+the documentation around you, rather than changing the existing
+prose.
+
+In general, documentation should describe what Perl does "now" rather
+than what it used to do.  It's perfectly reasonable to include notes
+in documentation about how behaviour has changed from previous releases,
+but, with very few exceptions, documentation isn't "dual-life" --
+it doesn't need to fully describe how all old versions used to work.
+
+
 =head1 CREDITS
 
-Social Contract about Contributed Modules originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters.
+"Social Contract about Contributed Modules" originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters.