X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/70e4a83b9a2f610546eb7adec04989f5f1052374..9e9fdd5de1676d607ddf9b9f10b8df2659af3ded:/pod/perlpolicy.pod diff --git a/pod/perlpolicy.pod b/pod/perlpolicy.pod index d9a0642..a36e1e0 100644 --- a/pod/perlpolicy.pod +++ b/pod/perlpolicy.pod @@ -8,6 +8,70 @@ 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 Eperl5-security-report@perl.orgE +to begin that process. + +=back + =head1 BACKWARD COMPATIBILITY AND DEPRECATION Our community has a long-held belief that backward-compatibility is a @@ -90,7 +154,7 @@ an experimental feature useful and want to help shape its future. =item deprecated If something in the Perl core is marked as B, we may remove it -from thecore in the next stable release series, though we may not. As of +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 @@ -159,6 +223,13 @@ 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. @@ -306,7 +377,45 @@ 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 and C, +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. 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 Erra@stanford.eduE and the perl5-porters. +"Social Contract about Contributed Modules" originally by Russ Allbery Erra@stanford.eduE and the perl5-porters.