This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #71998] overload::Method can die with blessed methods
[perl5.git] / pod / perlpolicy.pod
CommitLineData
48cb5b3a 1=head1 NAME
3c78fafa 2
48cb5b3a
JV
3perlpolicy - Various and sundry policies and commitments related to the perl core
4
5=head1 DESCRIPTION
6
7This document is the master document which records all written
8policies about how the Perl 5 Porters collectively develop and maintain
9the Perl core.
10
70e4a83b
JV
11=head1 BACKWARD COMPATIBILITY AND DEPRECATION
12
13Our community has a long-held belief that backward-compatibility is a
14virtue, even when the functionality in question is a design flaw.
15
16We would all love to unmake some mistakes we've made over the past
17decades. Living with every design error we've ever made can lead
18to painful stagnation. Unwinding our mistakes is very, very
19difficult. Doing so without actively harming our users is
20nearly impossible.
21
22Lately, ignoring or actively opposing compatibility with earlier versions
23of Perl has come into vogue. Sometimes, a change is proposed which
24wants to usurp syntax which previously had another meaning. Sometimes,
25a change wants to improve previously-crazy semantics.
26
27Down this road lies madness.
28
29Requiring end-user programmers to change just a few language constructs,
30even language constructs which no well-educated developer would ever
31intentionally use is tantamount to saying "you should not upgrade to
32a new release of Perl unless you have 100% test coverage and can do a
33full manual audit of your codebase." If we were to have tools capable of
34reliably upgrading Perl source code from one version of Perl to another,
35this concern could be significantly mitigated.
36
37We want to ensure that Perl continues to grow and flourish in the coming
38years and decades, but not at the expense of our user community.
39
40Existing syntax and semantics should only be marked for destruction in
41very limited circumstances. If a given language feature's continued
42inclusion in the language will cause significant harm to the language
43or prevent us from making needed changes to the runtime, then it may
44be considered for deprecation.
45
46Any language change which breaks backward-compatibility should be able to
47be enabled or disabled lexically. Unless code at a given scope declares
48that it wants the new behavior, that new behavior should be disabled.
49Which backward-incompatible changes are controlled implicitly by a
50'use v5.x.y' is a decision which should be made by the pumpking in
51consultation with the community.
52
53When a backward-incompatible change can't be toggled lexically, the decision
54to change the language must be considered very, very carefully. If it's
55possible to move the old syntax or semantics out of the core language
56and into XS-land, that XS module should be enabled by default unless
57the user declares that they want a newer revision of Perl.
58
59Historically, we've held ourselves to a far higher standard than
60backward-compatibility -- bugward-compatibility. Any accident of
61implementation or unintentional side-effect of running some bit of code
62has been considered to be a feature of the language to be defended with
63the same zeal as any other feature or functionality. No matter how
64frustrating these unintentional features may be to us as we continue
65to improve Perl, these unintentional features often deserve our
66protection. It is very important that existing software written in
67Perl continue to work correctly. If end-user developers have adopted a
68bug as a feature, we need to treat it as such.
69
70New syntax and semantics which don't break existing language constructs
71and syntax have a much lower bar. They merely need to prove themselves
72to be useful, elegant, well designed and well tested.
73
74=head2 Terminology
75
76To make sure we're talking about the same thing when we discuss the removal
77of features or functionality from the Perl core, we have specific definitions
78for a few words and phrases.
79
80=over
81
82=item experimental
83
84If something in the Perl core is marked as B<experimental>, we may change
85its behaviour, deprecate or remove it without notice. While we'll always
86do our best to smooth the transition path for users of experimental
87features, you should contact the perl5-porters mailinglist if you find
88an experimental feature useful and want to help shape its future.
89
90=item deprecated
91
92If something in the Perl core is marked as B<deprecated>, we may remove it
93from thecore in the next stable release series, though we may not. As of
94Perl 5.12, deprecated features and modules warn the user as they're used.
95If you use a deprecated feature and believe that its removal from the Perl
96core would be a mistake, please contact the perl5-porters mailinglist and
97plead your case. We don't deprecate things without a good reason, but
98sometimes there's a counterargument we haven't considered. Historically,
99we did not distinguish between "deprecated" and "discouraged" features.
100
101=item discouraged
102
103From time to time, we may mark language constructs and features which we
104consider to have been mistakes as B<discouraged>. Discouraged features
105aren't candidates for removal in the next major release series, but
106we may later deprecate them if they're found to stand in the way of a
107significant improvement to the core.
108
109=item removed
110
111Once a feature, construct or module has been marked as deprecated for a
112stable release cycle, we may remove it from the core. Unsurprisingly,
113we say we've B<removed> these things.
114
115=back
48cb5b3a 116
fcf56c88
JV
117=head1 MAINTENANCE BRANCHES
118
119=over
120
121=item *
122
123New releases of maint should contain as few changes as possible.
124If there is any question about whether a given patch might merit
125inclusion in a maint release, then it almost certainly should not
126be included.
127
128=item *
129
130Portability fixes, such as changes to Configure and the files in
131hints/ are acceptable. Ports of Perl to a new platform, architecture
132or OS release that involve changes to the implementation are NOT
133acceptable.
134
135=item *
136
137Documentation updates are acceptable.
138
139=item *
140
141Patches that add new warnings or errors or deprecate features
142are not acceptable.
143
144=item *
145
146Patches that fix crashing bugs that do not otherwise change Perl's
147functionality or negatively impact performance are acceptable.
148
149=item *
150
151Patches that fix CVEs or security issues are acceptable, but should
152be run through the perl5-security-report@perl.org mailing list
153rather than applied directly.
154
155=item *
156
157Updates to dual-life modules should consist of minimal patches to
158fix crashing or security issues (as above).
159
160=item *
161
162New versions of dual-life modules should NOT be imported into maint.
163Those belong in the next stable series.
164
165=item *
166
167Patches that add or remove features are not acceptable.
168
169=item *
170
171Patches that break binary compatibility are not acceptable. (Please
172talk to a pumpking.)
173
174=back
175
176
177=head2 Getting changes into a maint branch
178
179Historically, only the pumpking cherry-picked changes from bleadperl
180into maintperl. This has...scaling problems. At the same time,
181maintenance branches of stable versions of Perl need to be treated with
182great care. To that end, we're going to try out a new process for
183maint-5.12.
184
185Any committer may cherry-pick any commit from blead to maint-5.12 if
186they send mail to perl5-porters announcing their intent to cherry-pick
187a specific commit along with a rationale for doing so and at least two
188other committers respond to the list giving their assent. (This policy
189applies to current and former pumpkings, as well as other committers.)
48cb5b3a
JV
190
191=head1 CONTRIBUTED MODULES
192
193
194=head2 A Social Contract about Artistic Control
6ee623d5
GS
195
196What follows is a statement about artistic control, defined as the ability
197of authors of packages to guide the future of their code and maintain
198control over their work. It is a recognition that authors should have
199control over their work, and that it is a responsibility of the rest of
200the Perl community to ensure that they retain this control. It is an
201attempt to document the standards to which we, as Perl developers, intend
202to hold ourselves. It is an attempt to write down rough guidelines about
203the respect we owe each other as Perl developers.
204
205This statement is not a legal contract. This statement is not a legal
206document in any way, shape, or form. Perl is distributed under the GNU
207Public License and under the Artistic License; those are the precise legal
208terms. This statement isn't about the law or licenses. It's about
209community, mutual respect, trust, and good-faith cooperation.
210
211We recognize that the Perl core, defined as the software distributed with
212the heart of Perl itself, is a joint project on the part of all of us.
aaa2bbb1 213From time to time, a script, module, or set of modules (hereafter referred
6ee623d5
GS
214to simply as a "module") will prove so widely useful and/or so integral to
215the correct functioning of Perl itself that it should be distributed with
216Perl core. This should never be done without the author's explicit
217consent, and a clear recognition on all parts that this means the module
218is being distributed under the same terms as Perl itself. A module author
219should realize that inclusion of a module into the Perl core will
220necessarily mean some loss of control over it, since changes may
221occasionally have to be made on short notice or for consistency with the
222rest of Perl.
223
224Once a module has been included in the Perl core, however, everyone
225involved in maintaining Perl should be aware that the module is still the
226property of the original author unless the original author explicitly
227gives up their ownership of it. In particular:
228
48cb5b3a
JV
229=over
230
171407a0
JJ
231=item *
232
233The version of the module in the core should still be considered the
234work of the original author. All patches, bug reports, and so
235forth should be fed back to them. Their development directions
236should be respected whenever possible.
6ee623d5 237
48cb5b3a
JV
238=item *
239
240Patches may be applied by the pumpkin holder without the explicit
241cooperation of the module author if and only if they are very minor,
242time-critical in some fashion (such as urgent security fixes), or if
243the module author cannot be reached. Those patches must still be
244given back to the author when possible, and if the author decides on
245an alternate fix in their version, that fix should be strongly
246preferred unless there is a serious problem with it. Any changes not
247endorsed by the author should be marked as such, and the contributor
248of the change acknowledged.
249
250=item *
251
252The version of the module distributed with Perl should, whenever
253possible, be the latest version of the module as distributed by the
254author (the latest non-beta version in the case of public Perl
255releases), although the pumpkin holder may hold off on upgrading the
256version of the module distributed with Perl to the latest version
257until the latest version has had sufficient testing.
258
259=back
6ee623d5
GS
260
261In other words, the author of a module should be considered to have final
262say on modifications to their module whenever possible (bearing in mind
263that it's expected that everyone involved will work together and arrive at
264reasonable compromises when there are disagreements).
265
266As a last resort, however:
267
48cb5b3a
JV
268
269If the author's vision of the future of their module is sufficiently
270different from the vision of the pumpkin holder and perl5-porters as a
271whole so as to cause serious problems for Perl, the pumpkin holder may
272choose to formally fork the version of the module in the core from the
273one maintained by the author. This should not be done lightly and
c4f5d98d 274should B<always> if at all possible be done only after direct input
48cb5b3a
JV
275from Larry. If this is done, it must then be made explicit in the
276module as distributed with Perl core that it is a forked version and
277that while it is based on the original author's work, it is no longer
278maintained by them. This must be noted in both the documentation and
279in the comments in the source of the module.
6ee623d5
GS
280
281Again, this should be a last resort only. Ideally, this should never
282happen, and every possible effort at cooperation and compromise should be
283made before doing this. If it does prove necessary to fork a module for
284the overall health of Perl, proper credit must be given to the original
285author in perpetuity and the decision should be constantly re-evaluated to
286see if a remerging of the two branches is possible down the road.
287
288In all dealings with contributed modules, everyone maintaining Perl should
289keep in mind that the code belongs to the original author, that they may
290not be on perl5-porters at any given time, and that a patch is not
291official unless it has been integrated into the author's copy of the
292module. To aid with this, and with points #1, #2, and #3 above, contact
293information for the authors of all contributed modules should be kept with
294the Perl distribution.
295
296Finally, the Perl community as a whole recognizes that respect for
297ownership of code, respect for artistic control, proper credit, and active
298effort to prevent unintentional code skew or communication gaps is vital
299to the health of the community and Perl itself. Members of a community
300should not normally have to resort to rules and laws to deal with each
301other, and this document, although it contains rules so as to be clear, is
302about an attitude and general approach. The first step in any dispute
303should be open communication, respect for opposing views, and an attempt
304at a compromise. In nearly every circumstance nothing more will be
305necessary, and certainly no more drastic measure should be used until
306every avenue of communication and discussion has failed.
3c78fafa 307
70e4a83b 308
48cb5b3a
JV
309=head1 CREDITS
310
76caf4b8 311Social Contract about Contributed Modules originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters.
3c78fafa 312