Daftar Isi

• NAME
• DESCRIPTION
• GOVERNANCE
  • Perl 5 Porters
• MAINTENANCE AND SUPPORT
• BACKWARD COMPATIBILITY AND DEPRECATION
  • Terminology
• MAINTENANCE BRANCHES
  • Getting changes into a maint branch
• CONTRIBUTED MODULES
  • A Social Contract about Artistic Control
• DOCUMENTATION
• CREDITS

NAME

perlpolicy - Various and sundry policies and commitments related to the Perl core

DESCRIPTION

This document is the master document which records all writtenpolicies about how the Perl 5 Porters collectively develop and maintainthe Perl core.

GOVERNANCE

Perl 5 Porters

Subscribers to perl5-porters (the porters themselves) come in several flavours.Some are quiet curious lurkers, who rarely pitch in and instead watchthe ongoing development to ensure they're forewarned of new changes orfeatures in Perl. Some are representatives of vendors, who are thereto make sure that Perl continues to compile and work on theirplatforms. Some patch any reported bug that they know how to fix,some are actively patching their pet area (threads, Win32, the regexp-engine), while others seem to do nothing but complain. In otherwords, it's your usual mix of technical people.

Over this group of porters presides Larry Wall. He has the final wordin what does and does not change in any of the Perl programming languages.These days, Larry spends most of his time on Perl 6, while Perl 5 isshepherded by a "pumpking", a porter responsible for deciding whatgoes into each release and ensuring that releases happen on a regularbasis.

Larry sees Perl development along the lines of the US government:there's the Legislature (the porters), the Executive branch (the-pumpking), and the Supreme Court (Larry). The legislature candiscuss and submit patches to the executive branch all they like, butthe executive branch is free to veto them. Rarely, the Supreme Courtwill side with the executive branch over the legislature, or thelegislature over the executive branch. Mostly, however, thelegislature and the executive branch are supposed to get along andwork out their differences without impeachment or court cases.

You might sometimes see reference to Rule 1 and Rule 2. Larry's poweras Supreme Court is expressed in The Rules:

1

Larry is always by definition right about how Perl should behave.This means he has final veto power on the core functionality.

2

Larry is allowed to change his mind about any matter at a later date,regardless of whether he previously invoked Rule 1.

Got that? Larry is always right, even when he was wrong. It's rareto see either Rule exercised, but they are often alluded to.

MAINTENANCE AND SUPPORT

Perl 5 is developed by a community, not a corporate entity. Every changecontributed to the Perl core is the result of a donation. Typically, thesedonations are contributions of code or time by individual members of ourcommunity. On occasion, these donations come in the form of corporateor organizational sponsorship of a particular individual or project.

As a volunteer organization, the commitments we make are heavily dependenton the goodwill and hard work of individuals who have no obligation tocontribute to Perl.

That being said, we value Perl's stability and security and have longhad an unwritten covenant with the broader Perl community to supportand maintain releases of Perl.

This document codifies the support and maintenance commitments thatthe Perl community should expect from Perl's developers:

• We "officially" support the two most recent stable release series. 5.12.xand earlier are now out of support. As of the release of 5.18.0, we will"officially" end support for Perl 5.14.x, other than providing securityupdates as described below.

• To the best of our ability, we will attempt to fix critical issuesin the two most recent stable 5.x release series. Fixes for thecurrent release series take precedence over fixes for the previousrelease series.

• To the best of our ability, we will provide "critical" security patches/ releases for any major version of Perl whose 5.x.0 release was withinthe past three years. We can only commit to providing these for themost recent .y release in any 5.x.y series.

• We will not provide security updates or bug fixes for developmentreleases of Perl.

• We encourage vendors to ship the most recent supported release ofPerl at the time of their code freeze.

• As a vendor, you may have a requirement to backport security fixesbeyond our 3 year support commitment. We can provide limited support andadvice to you as you do so and, where possible will try to applythose patches to the relevant -maint branches in git, though we may ormay not choose to make numbered releases or "official" patchesavailable. Contact us at <[email protected]>to begin that process.

BACKWARD COMPATIBILITY AND DEPRECATION

Our community has a long-held belief that backward-compatibility is avirtue, even when the functionality in question is a design flaw.

We would all love to unmake some mistakes we've made over the pastdecades. Living with every design error we've ever made can leadto painful stagnation. Unwinding our mistakes is very, verydifficult. Doing so without actively harming our users isnearly impossible.

Lately, ignoring or actively opposing compatibility with earlier versionsof Perl has come into vogue. Sometimes, a change is proposed whichwants 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 everintentionally use is tantamount to saying "you should not upgrade toa new release of Perl unless you have 100% test coverage and can do afull manual audit of your codebase." If we were to have tools capable ofreliably 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 comingyears and decades, but not at the expense of our user community.

Existing syntax and semantics should only be marked for destruction invery limited circumstances. If a given language feature's continuedinclusion in the language will cause significant harm to the languageor prevent us from making needed changes to the runtime, then it maybe considered for deprecation.

Any language change which breaks backward-compatibility should be able tobe enabled or disabled lexically. Unless code at a given scope declaresthat 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 inconsultation with the community.

When a backward-incompatible change can't be toggled lexically, the decisionto change the language must be considered very, very carefully. If it'spossible to move the old syntax or semantics out of the core languageand into XS-land, that XS module should be enabled by default unlessthe user declares that they want a newer revision of Perl.

Historically, we've held ourselves to a far higher standard thanbackward-compatibility -- bugward-compatibility. Any accident ofimplementation or unintentional side-effect of running some bit of codehas been considered to be a feature of the language to be defended withthe same zeal as any other feature or functionality. No matter howfrustrating these unintentional features may be to us as we continueto improve Perl, these unintentional features often deserve ourprotection. It is very important that existing software written inPerl continue to work correctly. If end-user developers have adopted abug as a feature, we need to treat it as such.

New syntax and semantics which don't break existing language constructsand syntax have a much lower bar. They merely need to prove themselvesto be useful, elegant, well designed, and well tested.

Terminology

To make sure we're talking about the same thing when we discuss the removalof features or functionality from the Perl core, we have specific definitionsfor a few words and phrases.

• experimental

  If something in the Perl core is marked as experimental, we may changeits behaviour, deprecate or remove it without notice. While we'll alwaysdo our best to smooth the transition path for users of experimentalfeatures, you should contact the perl5-porters mailinglist if you findan experimental feature useful and want to help shape its future.

• deprecated

  If something in the Perl core is marked as deprecated, we may remove itfrom the core in the next stable release series, though we may not. As ofPerl 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 Perlcore would be a mistake, please contact the perl5-porters mailinglist andplead your case. We don't deprecate things without a good reason, butsometimes there's a counterargument we haven't considered. Historically,we did not distinguish between "deprecated" and "discouraged" features.

• discouraged

  From time to time, we may mark language constructs and features which weconsider to have been mistakes as discouraged. Discouraged featuresaren't candidates for removal in the next major release series, butwe may later deprecate them if they're found to stand in the way of asignificant improvement to the Perl core.

• removed

  Once a feature, construct or module has been marked as deprecated for astable release cycle, we may remove it from the Perl core. Unsurprisingly,we say we've removed these things.

MAINTENANCE BRANCHES

• New releases of maint should contain as few changes as possible.If there is any question about whether a given patch might meritinclusion in a maint release, then it almost certainly should notbe included.

• Portability fixes, such as changes to Configure and the files inhints/ are acceptable. Ports of Perl to a new platform, architectureor OS release that involve changes to the implementation are NOTacceptable.

• Acceptable documentation updates are those that correct factual errors,explain significant bugs or deficiencies in the current implementation, or fix broken markup.

• Patches that add new warnings or errors or deprecate featuresare not acceptable.

• Patches that fix crashing bugs that do not otherwise change Perl'sfunctionality or negatively impact performance are acceptable.

• Patches that fix CVEs or security issues are acceptable, but shouldbe run through the [email protected] mailing listrather than applied directly.

• Patches that fix regressions in perl's behavior relative to previousreleases are acceptable.

• Updates to dual-life modules should consist of minimal patches to fix crashing or security issues (as above).

• Minimal patches that fix platform-specific test failures orinstallation issues are acceptable. When these changes are madeto dual-life modules for which CPAN is canonical, any changesshould be coordinated with the upstream author.

• New versions of dual-life modules should NOT be imported into maint.Those belong in the next stable series.

• Patches that add or remove features are not acceptable.

• Patches that break binary compatibility are not acceptable. (Pleasetalk to a pumpking.)

Getting changes into a maint branch

Historically, only the pumpking cherry-picked changes from bleadperlinto maintperl. This has...scaling problems. At the same time,maintenance branches of stable versions of Perl need to be treated withgreat care. To that end, we're going to try out a new process formaint-5.12.

Any committer may cherry-pick any commit from blead to maint-5.12 ifthey send mail to perl5-porters announcing their intent to cherry-picka specific commit along with a rationale for doing so and at least two other committers respond to the list giving their assent. (This policyapplies to current and former pumpkings, as well as other committers.)

CONTRIBUTED MODULES

A Social Contract about Artistic Control

What follows is a statement about artistic control, defined as the abilityof authors of packages to guide the future of their code and maintaincontrol over their work. It is a recognition that authors should havecontrol over their work, and that it is a responsibility of the rest ofthe Perl community to ensure that they retain this control. It is anattempt to document the standards to which we, as Perl developers, intendto hold ourselves. It is an attempt to write down rough guidelines aboutthe respect we owe each other as Perl developers.

This statement is not a legal contract. This statement is not a legaldocument in any way, shape, or form. Perl is distributed under the GNUPublic License and under the Artistic License; those are the precise legalterms. This statement isn't about the law or licenses. It's aboutcommunity, mutual respect, trust, and good-faith cooperation.

We recognize that the Perl core, defined as the software distributed withthe heart of Perl itself, is a joint project on the part of all of us.From time to time, a script, module, or set of modules (hereafter referredto simply as a "module") will prove so widely useful and/or so integral tothe correct functioning of Perl itself that it should be distributed withthe Perl core. This should never be done without the author's explicitconsent, and a clear recognition on all parts that this means the moduleis being distributed under the same terms as Perl itself. A module authorshould realize that inclusion of a module into the Perl core willnecessarily mean some loss of control over it, since changes mayoccasionally have to be made on short notice or for consistency with therest of Perl.

Once a module has been included in the Perl core, however, everyoneinvolved in maintaining Perl should be aware that the module is still theproperty of the original author unless the original author explicitlygives up their ownership of it. In particular:

• The version of the module in the Perl core should still be considered thework of the original author. All patches, bug reports, and soforth should be fed back to them. Their development directionsshould be respected whenever possible.

• Patches may be applied by the pumpkin holder without the explicitcooperation of the module author if and only if they are very minor,time-critical in some fashion (such as urgent security fixes), or ifthe module author cannot be reached. Those patches must still begiven back to the author when possible, and if the author decides onan alternate fix in their version, that fix should be stronglypreferred unless there is a serious problem with it. Any changes notendorsed by the author should be marked as such, and the contributorof the change acknowledged.

• The version of the module distributed with Perl should, wheneverpossible, be the latest version of the module as distributed by theauthor (the latest non-beta version in the case of public Perlreleases), although the pumpkin holder may hold off on upgrading theversion of the module distributed with Perl to the latest versionuntil the latest version has had sufficient testing.

In other words, the author of a module should be considered to have finalsay on modifications to their module whenever possible (bearing in mindthat it's expected that everyone involved will work together and arrive atreasonable compromises when there are disagreements).

As a last resort, however:

If the author's vision of the future of their module is sufficientlydifferent from the vision of the pumpkin holder and perl5-porters as awhole so as to cause serious problems for Perl, the pumpkin holder maychoose to formally fork the version of the module in the Perl core from theone maintained by the author. This should not be done lightly andshould always if at all possible be done only after direct inputfrom Larry. If this is done, it must then be made explicit in themodule as distributed with the Perl core that it is a forked version andthat while it is based on the original author's work, it is no longermaintained by them. This must be noted in both the documentation andin the comments in the source of the module.

Again, this should be a last resort only. Ideally, this should neverhappen, and every possible effort at cooperation and compromise should bemade before doing this. If it does prove necessary to fork a module forthe overall health of Perl, proper credit must be given to the originalauthor in perpetuity and the decision should be constantly re-evaluated tosee if a remerging of the two branches is possible down the road.

In all dealings with contributed modules, everyone maintaining Perl shouldkeep in mind that the code belongs to the original author, that they maynot be on perl5-porters at any given time, and that a patch is notofficial unless it has been integrated into the author's copy of themodule. To aid with this, and with points #1, #2, and #3 above, contactinformation for the authors of all contributed modules should be kept withthe Perl distribution.

Finally, the Perl community as a whole recognizes that respect forownership of code, respect for artistic control, proper credit, and activeeffort to prevent unintentional code skew or communication gaps is vitalto the health of the community and Perl itself. Members of a communityshould not normally have to resort to rules and laws to deal with eachother, and this document, although it contains rules so as to be clear, isabout an attitude and general approach. The first step in any disputeshould be open communication, respect for opposing views, and an attemptat a compromise. In nearly every circumstance nothing more will benecessary, and certainly no more drastic measure should be used untilevery avenue of communication and discussion has failed.

DOCUMENTATION

Perl's documentation is an important resource for our users. It'sincredibly important for Perl's documentation to be reasonably coherentand to accurately reflect the current implementation.

Just as P5P collectively maintains the codebase, we collectivelymaintain the documentation. Writing a particular bit of documentationdoesn't give an author control of the future of that documentation.At the same time, just as source code changes should match the styleof their surrounding blocks, so should documentation changes.

Examples in documentation should be illustrative of the conceptthey're explaining. Sometimes, the best way to show how alanguage feature works is with a small program the reader canrun without modification. More often, examples will consistof a snippet of code containing only the "important" bits.The definition of "important" varies from snippet to snippet.Sometimes it's important to declare use strict and use warnings,initialize all variables and fully catch every error condition.More often than not, though, those things obscure the lessonthe example was intended to teach.

As Perl is developed by a global team of volunteers, ourdocumentation often contains spellings which look funnyto somebody. Choice of American/British/Other spellingsis left as an exercise for the author of each bit ofdocumentation. When patching documentation, try to emulatethe documentation around you, rather than changing the existingprose.

In general, documentation should describe what Perl does "now" ratherthan what it used to do. It's perfectly reasonable to include notesin 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.

CREDITS

"Social Contract about Contributed Modules" originally by Russ Allbery <[email protected]> and the perl5-porters.