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