Commit | Line | Data |
---|---|---|
3db23aec SH |
1 | =encoding utf8 |
2 | ||
48cb5b3a | 3 | =head1 NAME |
3c78fafa | 4 | |
9a7064ee | 5 | perlpolicy - Various and sundry policies and commitments related to the Perl core |
48cb5b3a JV |
6 | |
7 | =head1 DESCRIPTION | |
8 | ||
9 | This document is the master document which records all written | |
10 | policies about how the Perl 5 Porters collectively develop and maintain | |
11 | the Perl core. | |
12 | ||
a101a770 JV |
13 | =head1 GOVERNANCE |
14 | ||
15 | =head2 Perl 5 Porters | |
16 | ||
17 | Subscribers to perl5-porters (the porters themselves) come in several flavours. | |
18 | Some are quiet curious lurkers, who rarely pitch in and instead watch | |
19 | the ongoing development to ensure they're forewarned of new changes or | |
20 | features in Perl. Some are representatives of vendors, who are there | |
21 | to make sure that Perl continues to compile and work on their | |
22 | platforms. Some patch any reported bug that they know how to fix, | |
23 | some are actively patching their pet area (threads, Win32, the regexp | |
24 | -engine), while others seem to do nothing but complain. In other | |
25 | words, it's your usual mix of technical people. | |
26 | ||
27 | Over this group of porters presides Larry Wall. He has the final word | |
28 | in what does and does not change in any of the Perl programming languages. | |
29 | These days, Larry spends most of his time on Perl 6, while Perl 5 is | |
30 | shepherded by a "pumpking", a porter responsible for deciding what | |
31 | goes into each release and ensuring that releases happen on a regular | |
32 | basis. | |
33 | ||
34 | Larry sees Perl development along the lines of the US government: | |
35 | there's the Legislature (the porters), the Executive branch (the | |
36 | -pumpking), and the Supreme Court (Larry). The legislature can | |
37 | discuss and submit patches to the executive branch all they like, but | |
38 | the executive branch is free to veto them. Rarely, the Supreme Court | |
39 | will side with the executive branch over the legislature, or the | |
40 | legislature over the executive branch. Mostly, however, the | |
41 | legislature and the executive branch are supposed to get along and | |
42 | work out their differences without impeachment or court cases. | |
43 | ||
44 | You might sometimes see reference to Rule 1 and Rule 2. Larry's power | |
45 | as Supreme Court is expressed in The Rules: | |
46 | ||
47 | =over 4 | |
48 | ||
49 | =item 1 | |
50 | ||
51 | Larry is always by definition right about how Perl should behave. | |
52 | This means he has final veto power on the core functionality. | |
53 | ||
54 | =item 2 | |
55 | ||
56 | Larry is allowed to change his mind about any matter at a later date, | |
57 | regardless of whether he previously invoked Rule 1. | |
58 | ||
59 | =back | |
60 | ||
61 | Got that? Larry is always right, even when he was wrong. It's rare | |
62 | to see either Rule exercised, but they are often alluded to. | |
63 | ||
70eadc36 JV |
64 | =head1 MAINTENANCE AND SUPPORT |
65 | ||
66 | Perl 5 is developed by a community, not a corporate entity. Every change | |
67 | contributed to the Perl core is the result of a donation. Typically, these | |
68 | donations are contributions of code or time by individual members of our | |
69 | community. On occasion, these donations come in the form of corporate | |
70 | or organizational sponsorship of a particular individual or project. | |
71 | ||
72 | As a volunteer organization, the commitments we make are heavily dependent | |
73 | on the goodwill and hard work of individuals who have no obligation to | |
74 | contribute to Perl. | |
75 | ||
3b4ebcde | 76 | That being said, we value Perl's stability and security and have long |
70eadc36 JV |
77 | had an unwritten covenant with the broader Perl community to support |
78 | and maintain releases of Perl. | |
79 | ||
80 | This document codifies the support and maintenance commitments that | |
81 | the Perl community should expect from Perl's developers: | |
82 | ||
83 | =over | |
84 | ||
85 | =item * | |
86 | ||
965d3000 MH |
87 | We "officially" support the two most recent stable release series. 5.16.x |
88 | and earlier are now out of support. As of the release of 5.22.0, we will | |
89 | "officially" end support for Perl 5.18.x, other than providing security | |
70eadc36 JV |
90 | updates as described below. |
91 | ||
92 | =item * | |
93 | ||
94 | To the best of our ability, we will attempt to fix critical issues | |
e26b5c49 | 95 | in the two most recent stable 5.x release series. Fixes for the |
70eadc36 JV |
96 | current release series take precedence over fixes for the previous |
97 | release series. | |
98 | ||
99 | =item * | |
100 | ||
101 | To the best of our ability, we will provide "critical" security patches | |
f50f542d | 102 | / releases for any major version of Perl whose 5.x.0 release was within |
70a565f4 RS |
103 | the past three years. We can only commit to providing these for the |
104 | most recent .y release in any 5.x.y series. | |
70eadc36 JV |
105 | |
106 | =item * | |
107 | ||
108 | We will not provide security updates or bug fixes for development | |
109 | releases of Perl. | |
110 | ||
111 | =item * | |
112 | ||
113 | We encourage vendors to ship the most recent supported release of | |
114 | Perl at the time of their code freeze. | |
115 | ||
116 | =item * | |
117 | ||
118 | As a vendor, you may have a requirement to backport security fixes | |
119 | beyond our 3 year support commitment. We can provide limited support and | |
120 | advice to you as you do so and, where possible will try to apply | |
121 | those patches to the relevant -maint branches in git, though we may or | |
122 | may not choose to make numbered releases or "official" patches | |
123 | available. Contact us at E<lt>perl5-security-report@perl.orgE<gt> | |
124 | to begin that process. | |
125 | ||
126 | =back | |
127 | ||
70e4a83b JV |
128 | =head1 BACKWARD COMPATIBILITY AND DEPRECATION |
129 | ||
130 | Our community has a long-held belief that backward-compatibility is a | |
131 | virtue, even when the functionality in question is a design flaw. | |
132 | ||
133 | We would all love to unmake some mistakes we've made over the past | |
134 | decades. Living with every design error we've ever made can lead | |
135 | to painful stagnation. Unwinding our mistakes is very, very | |
136 | difficult. Doing so without actively harming our users is | |
137 | nearly impossible. | |
138 | ||
139 | Lately, ignoring or actively opposing compatibility with earlier versions | |
140 | of Perl has come into vogue. Sometimes, a change is proposed which | |
141 | wants to usurp syntax which previously had another meaning. Sometimes, | |
339a461d | 142 | a change wants to improve previously-crazy semantics. |
70e4a83b JV |
143 | |
144 | Down this road lies madness. | |
145 | ||
146 | Requiring end-user programmers to change just a few language constructs, | |
147 | even language constructs which no well-educated developer would ever | |
148 | intentionally use is tantamount to saying "you should not upgrade to | |
149 | a new release of Perl unless you have 100% test coverage and can do a | |
150 | full manual audit of your codebase." If we were to have tools capable of | |
151 | reliably upgrading Perl source code from one version of Perl to another, | |
152 | this concern could be significantly mitigated. | |
153 | ||
154 | We want to ensure that Perl continues to grow and flourish in the coming | |
155 | years and decades, but not at the expense of our user community. | |
156 | ||
157 | Existing syntax and semantics should only be marked for destruction in | |
1adbeba0 | 158 | very limited circumstances. If they are believed to be very rarely used, |
667f5e7f RS |
159 | stand in the way of actual improvement to the Perl language or perl |
160 | interpreter, and if affected code can be easily updated to continue | |
161 | working, they may be considered for removal. When in doubt, caution | |
162 | dictates that we will favor backward compatibility. When a feature is | |
163 | deprecated, a statement of reasoning describing the decision process | |
164 | will be posted, and a link to it will be provided in the relevant | |
165 | perldelta documents. | |
5ae454f0 RS |
166 | |
167 | Using a lexical pragma to enable or disable legacy behavior should be | |
168 | considered when appropriate, and in the absence of any pragma legacy | |
169 | behavior should be enabled. Which backward-incompatible changes are | |
170 | controlled implicitly by a 'use v5.x.y' is a decision which should be | |
171 | made by the pumpking in consultation with the community. | |
70e4a83b JV |
172 | |
173 | Historically, we've held ourselves to a far higher standard than | |
174 | backward-compatibility -- bugward-compatibility. Any accident of | |
175 | implementation or unintentional side-effect of running some bit of code | |
176 | has been considered to be a feature of the language to be defended with | |
177 | the same zeal as any other feature or functionality. No matter how | |
178 | frustrating these unintentional features may be to us as we continue | |
179 | to improve Perl, these unintentional features often deserve our | |
180 | protection. It is very important that existing software written in | |
181 | Perl continue to work correctly. If end-user developers have adopted a | |
182 | bug as a feature, we need to treat it as such. | |
183 | ||
184 | New syntax and semantics which don't break existing language constructs | |
185 | and syntax have a much lower bar. They merely need to prove themselves | |
b50cfd0a RS |
186 | to be useful, elegant, well designed, and well tested. In most cases, |
187 | these additions will be marked as I<experimental> for some time. See | |
188 | below for more on that. | |
70e4a83b JV |
189 | |
190 | =head2 Terminology | |
191 | ||
192 | To make sure we're talking about the same thing when we discuss the removal | |
193 | of features or functionality from the Perl core, we have specific definitions | |
194 | for a few words and phrases. | |
195 | ||
196 | =over | |
197 | ||
198 | =item experimental | |
199 | ||
200 | If something in the Perl core is marked as B<experimental>, we may change | |
201 | its behaviour, deprecate or remove it without notice. While we'll always | |
202 | do our best to smooth the transition path for users of experimental | |
203 | features, you should contact the perl5-porters mailinglist if you find | |
204 | an experimental feature useful and want to help shape its future. | |
205 | ||
f1126a90 RS |
206 | Experimental features must be experimental in two stable releases before being |
207 | marked non-experimental. Experimental features will only have their | |
208 | experimental status revoked when they no longer have any design-changing bugs | |
209 | open against them and when they have remained unchanged in behavior for the | |
210 | entire length of a development cycle. In other words, a feature present in | |
211 | v5.20.0 may be marked no longer experimental in v5.22.0 if and only if its | |
212 | behavior is unchanged throughout all of v5.21. | |
213 | ||
70e4a83b JV |
214 | =item deprecated |
215 | ||
216 | If something in the Perl core is marked as B<deprecated>, we may remove it | |
5c5fd8eb KW |
217 | from the core in the future, though we might not. Generally, backward |
218 | incompatible changes will have deprecation warnings for two release | |
219 | cycles before being removed, but may be removed after just one cycle if | |
220 | the risk seems quite low or the benefits quite high. | |
221 | ||
222 | As of | |
70e4a83b | 223 | Perl 5.12, deprecated features and modules warn the user as they're used. |
42b68fb1 DG |
224 | When a module is deprecated, it will also be made available on CPAN. |
225 | Installing it from CPAN will silence deprecation warnings for that module. | |
226 | ||
227 | If you use a deprecated feature or module and believe that its removal from | |
228 | the Perl core would be a mistake, please contact the perl5-porters | |
229 | mailinglist and plead your case. We don't deprecate things without a good | |
230 | reason, but sometimes there's a counterargument we haven't considered. | |
231 | Historically, we did not distinguish between "deprecated" and "discouraged" | |
232 | features. | |
70e4a83b JV |
233 | |
234 | =item discouraged | |
235 | ||
236 | From time to time, we may mark language constructs and features which we | |
237 | consider to have been mistakes as B<discouraged>. Discouraged features | |
5c5fd8eb | 238 | aren't currently candidates for removal, but |
70e4a83b | 239 | we may later deprecate them if they're found to stand in the way of a |
9a7064ee | 240 | significant improvement to the Perl core. |
70e4a83b JV |
241 | |
242 | =item removed | |
243 | ||
5c5fd8eb KW |
244 | Once a feature, construct or module has been marked as deprecated, we |
245 | may remove it from the Perl core. Unsurprisingly, | |
42b68fb1 DG |
246 | we say we've B<removed> these things. When a module is removed, it will |
247 | no longer ship with Perl, but will continue to be available on CPAN. | |
70e4a83b JV |
248 | |
249 | =back | |
48cb5b3a | 250 | |
fcf56c88 JV |
251 | =head1 MAINTENANCE BRANCHES |
252 | ||
366d02b5 SH |
253 | New releases of maintenance branches should only contain changes that fall into |
254 | one of the "acceptable" categories set out below, but must not contain any | |
255 | changes that fall into one of the "unacceptable" categories. (For example, a | |
256 | fix for a crashing bug must not be included if it breaks binary compatibility.) | |
257 | ||
258 | It is not necessary to include every change meeting these criteria, and in | |
259 | general the focus should be on addressing security issues, crashing bugs, | |
260 | regressions and serious installation issues. The temptation to include a | |
261 | plethora of minor changes that don't affect the installation or execution of | |
262 | perl (e.g. spelling corrections in documentation) should be resisted in order | |
263 | to reduce the overall risk of overlooking something. The intention is to | |
264 | create maintenance releases which are both worthwhile and which users can have | |
265 | full confidence in the stability of. (A secondary concern is to avoid burning | |
266 | out the maint-pumpking or overwhelming other committers voting on changes to be | |
267 | included (see L</"Getting changes into a maint branch"> below).) | |
fcf56c88 | 268 | |
c792d632 SH |
269 | The following types of change may be considered acceptable, as long as they do |
270 | not also fall into any of the "unacceptable" categories set out below: | |
271 | ||
272 | =over | |
273 | ||
fcf56c88 JV |
274 | =item * |
275 | ||
79f83602 | 276 | Patches that fix CVEs or security issues. These changes should |
64b35da5 SH |
277 | be run through the perl5-security-report@perl.org mailing list |
278 | rather than applied directly. | |
fcf56c88 JV |
279 | |
280 | =item * | |
281 | ||
4c0ef208 | 282 | Patches that fix crashing bugs, assertion failures and |
a6f83414 | 283 | memory corruption but which do not otherwise change perl's |
79f83602 | 284 | functionality or negatively impact performance. |
fcf56c88 JV |
285 | |
286 | =item * | |
287 | ||
56b40e63 | 288 | Patches that fix regressions in perl's behavior relative to previous |
fc088d5f SH |
289 | releases, no matter how old the regression, since some people may |
290 | upgrade from very old versions of perl to the latest version. | |
56b40e63 RS |
291 | |
292 | =item * | |
293 | ||
e2b7b23f SH |
294 | Patches that fix anything which prevents or seriously impacts the build |
295 | or installation of perl. | |
296 | ||
297 | =item * | |
298 | ||
64b35da5 | 299 | Portability fixes, such as changes to Configure and the files in |
79f83602 | 300 | the hints/ folder. |
fcf56c88 JV |
301 | |
302 | =item * | |
303 | ||
e2b7b23f | 304 | Minimal patches that fix platform-specific test failures. |
27d0393b | 305 | |
64b35da5 SH |
306 | =item * |
307 | ||
79f83602 SH |
308 | Documentation updates that correct factual errors, explain significant |
309 | bugs or deficiencies in the current implementation, or fix broken markup. | |
64b35da5 SH |
310 | |
311 | =item * | |
312 | ||
313 | Updates to dual-life modules should consist of minimal patches to | |
b33e5804 SH |
314 | fix crashing bugs or security issues (as above). Any changes made to |
315 | dual-life modules for which CPAN is canonical should be coordinated with | |
316 | the upstream author. | |
64b35da5 | 317 | |
c792d632 SH |
318 | =back |
319 | ||
320 | The following types of change are NOT acceptable: | |
321 | ||
322 | =over | |
323 | ||
324 | =item * | |
325 | ||
79f83602 | 326 | Patches that break binary compatibility. (Please talk to a pumpking.) |
c792d632 SH |
327 | |
328 | =item * | |
329 | ||
79f83602 | 330 | Patches that add or remove features. |
c792d632 | 331 | |
27d0393b JV |
332 | =item * |
333 | ||
79f83602 | 334 | Patches that add new warnings or errors or deprecate features. |
fcf56c88 JV |
335 | |
336 | =item * | |
337 | ||
79f83602 SH |
338 | Ports of Perl to a new platform, architecture or OS release that |
339 | involve changes to the implementation. | |
fcf56c88 JV |
340 | |
341 | =item * | |
342 | ||
64b35da5 SH |
343 | New versions of dual-life modules should NOT be imported into maint. |
344 | Those belong in the next stable series. | |
fcf56c88 JV |
345 | |
346 | =back | |
347 | ||
a969a3c5 SH |
348 | If there is any question about whether a given patch might merit |
349 | inclusion in a maint release, then it almost certainly should not | |
350 | be included. | |
351 | ||
fcf56c88 JV |
352 | =head2 Getting changes into a maint branch |
353 | ||
354 | Historically, only the pumpking cherry-picked changes from bleadperl | |
e566981e | 355 | into maintperl. This has scaling problems. At the same time, |
fcf56c88 | 356 | maintenance branches of stable versions of Perl need to be treated with |
e566981e DG |
357 | great care. To that end, as of Perl 5.12, we have a new process for |
358 | maint branches. | |
fcf56c88 | 359 | |
e566981e | 360 | Any committer may cherry-pick any commit from blead to a maint branch if |
fcf56c88 | 361 | they send mail to perl5-porters announcing their intent to cherry-pick |
17c80487 | 362 | a specific commit along with a rationale for doing so and at least two |
fcf56c88 JV |
363 | other committers respond to the list giving their assent. (This policy |
364 | applies to current and former pumpkings, as well as other committers.) | |
48cb5b3a | 365 | |
6788bcfc SH |
366 | Other voting mechanisms may be used instead, as long as the same number of |
367 | votes is gathered in a transparent manner. Specifically, proposals of | |
368 | which changes to cherry-pick must be visible to everyone on perl5-porters | |
369 | so that the views of everyone interested may be heard. | |
370 | ||
402f2e6a SH |
371 | It is not necessary for voting to be held on cherry-picking perldelta |
372 | entries associated with changes that have already been cherry-picked, nor | |
373 | for the maint-pumpking to obtain votes on changes required by the | |
374 | F<Porting/release_managers_guide.pod> where such changes can be applied by | |
375 | the means of cherry-picking from blead. | |
376 | ||
48cb5b3a JV |
377 | =head1 CONTRIBUTED MODULES |
378 | ||
379 | ||
380 | =head2 A Social Contract about Artistic Control | |
6ee623d5 GS |
381 | |
382 | What follows is a statement about artistic control, defined as the ability | |
383 | of authors of packages to guide the future of their code and maintain | |
384 | control over their work. It is a recognition that authors should have | |
385 | control over their work, and that it is a responsibility of the rest of | |
386 | the Perl community to ensure that they retain this control. It is an | |
387 | attempt to document the standards to which we, as Perl developers, intend | |
388 | to hold ourselves. It is an attempt to write down rough guidelines about | |
389 | the respect we owe each other as Perl developers. | |
390 | ||
391 | This statement is not a legal contract. This statement is not a legal | |
392 | document in any way, shape, or form. Perl is distributed under the GNU | |
393 | Public License and under the Artistic License; those are the precise legal | |
394 | terms. This statement isn't about the law or licenses. It's about | |
395 | community, mutual respect, trust, and good-faith cooperation. | |
396 | ||
397 | We recognize that the Perl core, defined as the software distributed with | |
398 | the heart of Perl itself, is a joint project on the part of all of us. | |
aaa2bbb1 | 399 | From time to time, a script, module, or set of modules (hereafter referred |
6ee623d5 GS |
400 | to simply as a "module") will prove so widely useful and/or so integral to |
401 | the correct functioning of Perl itself that it should be distributed with | |
9a7064ee | 402 | the Perl core. This should never be done without the author's explicit |
6ee623d5 GS |
403 | consent, and a clear recognition on all parts that this means the module |
404 | is being distributed under the same terms as Perl itself. A module author | |
405 | should realize that inclusion of a module into the Perl core will | |
406 | necessarily mean some loss of control over it, since changes may | |
407 | occasionally have to be made on short notice or for consistency with the | |
408 | rest of Perl. | |
409 | ||
410 | Once a module has been included in the Perl core, however, everyone | |
411 | involved in maintaining Perl should be aware that the module is still the | |
412 | property of the original author unless the original author explicitly | |
413 | gives up their ownership of it. In particular: | |
414 | ||
48cb5b3a JV |
415 | =over |
416 | ||
171407a0 JJ |
417 | =item * |
418 | ||
9a7064ee | 419 | The version of the module in the Perl core should still be considered the |
171407a0 JJ |
420 | work of the original author. All patches, bug reports, and so |
421 | forth should be fed back to them. Their development directions | |
422 | should be respected whenever possible. | |
6ee623d5 | 423 | |
48cb5b3a JV |
424 | =item * |
425 | ||
426 | Patches may be applied by the pumpkin holder without the explicit | |
427 | cooperation of the module author if and only if they are very minor, | |
428 | time-critical in some fashion (such as urgent security fixes), or if | |
429 | the module author cannot be reached. Those patches must still be | |
430 | given back to the author when possible, and if the author decides on | |
431 | an alternate fix in their version, that fix should be strongly | |
432 | preferred unless there is a serious problem with it. Any changes not | |
433 | endorsed by the author should be marked as such, and the contributor | |
434 | of the change acknowledged. | |
435 | ||
436 | =item * | |
437 | ||
438 | The version of the module distributed with Perl should, whenever | |
439 | possible, be the latest version of the module as distributed by the | |
440 | author (the latest non-beta version in the case of public Perl | |
441 | releases), although the pumpkin holder may hold off on upgrading the | |
442 | version of the module distributed with Perl to the latest version | |
443 | until the latest version has had sufficient testing. | |
444 | ||
445 | =back | |
6ee623d5 GS |
446 | |
447 | In other words, the author of a module should be considered to have final | |
448 | say on modifications to their module whenever possible (bearing in mind | |
449 | that it's expected that everyone involved will work together and arrive at | |
450 | reasonable compromises when there are disagreements). | |
451 | ||
452 | As a last resort, however: | |
453 | ||
48cb5b3a JV |
454 | |
455 | If the author's vision of the future of their module is sufficiently | |
456 | different from the vision of the pumpkin holder and perl5-porters as a | |
457 | whole so as to cause serious problems for Perl, the pumpkin holder may | |
9a7064ee | 458 | choose to formally fork the version of the module in the Perl core from the |
48cb5b3a | 459 | one maintained by the author. This should not be done lightly and |
c4f5d98d | 460 | should B<always> if at all possible be done only after direct input |
48cb5b3a | 461 | from Larry. If this is done, it must then be made explicit in the |
9a7064ee | 462 | module as distributed with the Perl core that it is a forked version and |
48cb5b3a JV |
463 | that while it is based on the original author's work, it is no longer |
464 | maintained by them. This must be noted in both the documentation and | |
465 | in the comments in the source of the module. | |
6ee623d5 GS |
466 | |
467 | Again, this should be a last resort only. Ideally, this should never | |
468 | happen, and every possible effort at cooperation and compromise should be | |
469 | made before doing this. If it does prove necessary to fork a module for | |
470 | the overall health of Perl, proper credit must be given to the original | |
471 | author in perpetuity and the decision should be constantly re-evaluated to | |
472 | see if a remerging of the two branches is possible down the road. | |
473 | ||
474 | In all dealings with contributed modules, everyone maintaining Perl should | |
475 | keep in mind that the code belongs to the original author, that they may | |
476 | not be on perl5-porters at any given time, and that a patch is not | |
477 | official unless it has been integrated into the author's copy of the | |
478 | module. To aid with this, and with points #1, #2, and #3 above, contact | |
479 | information for the authors of all contributed modules should be kept with | |
480 | the Perl distribution. | |
481 | ||
482 | Finally, the Perl community as a whole recognizes that respect for | |
483 | ownership of code, respect for artistic control, proper credit, and active | |
484 | effort to prevent unintentional code skew or communication gaps is vital | |
485 | to the health of the community and Perl itself. Members of a community | |
486 | should not normally have to resort to rules and laws to deal with each | |
487 | other, and this document, although it contains rules so as to be clear, is | |
488 | about an attitude and general approach. The first step in any dispute | |
489 | should be open communication, respect for opposing views, and an attempt | |
490 | at a compromise. In nearly every circumstance nothing more will be | |
491 | necessary, and certainly no more drastic measure should be used until | |
492 | every avenue of communication and discussion has failed. | |
3c78fafa | 493 | |
70e4a83b | 494 | |
3b4ebcde JV |
495 | =head1 DOCUMENTATION |
496 | ||
497 | Perl's documentation is an important resource for our users. It's | |
498 | incredibly important for Perl's documentation to be reasonably coherent | |
499 | and to accurately reflect the current implementation. | |
500 | ||
501 | Just as P5P collectively maintains the codebase, we collectively | |
502 | maintain the documentation. Writing a particular bit of documentation | |
503 | doesn't give an author control of the future of that documentation. | |
504 | At the same time, just as source code changes should match the style | |
505 | of their surrounding blocks, so should documentation changes. | |
506 | ||
507 | Examples in documentation should be illustrative of the concept | |
508 | they're explaining. Sometimes, the best way to show how a | |
509 | language feature works is with a small program the reader can | |
510 | run without modification. More often, examples will consist | |
511 | of a snippet of code containing only the "important" bits. | |
512 | The definition of "important" varies from snippet to snippet. | |
1bb8a155 | 513 | Sometimes it's important to declare C<use strict> and C<use warnings>, |
3b4ebcde JV |
514 | initialize all variables and fully catch every error condition. |
515 | More often than not, though, those things obscure the lesson | |
516 | the example was intended to teach. | |
517 | ||
518 | As Perl is developed by a global team of volunteers, our | |
519 | documentation often contains spellings which look funny | |
520 | to I<somebody>. Choice of American/British/Other spellings | |
521 | is left as an exercise for the author of each bit of | |
522 | documentation. When patching documentation, try to emulate | |
523 | the documentation around you, rather than changing the existing | |
524 | prose. | |
525 | ||
526 | In general, documentation should describe what Perl does "now" rather | |
527 | than what it used to do. It's perfectly reasonable to include notes | |
528 | in documentation about how behaviour has changed from previous releases, | |
9e9fdd5d | 529 | but, with very few exceptions, documentation isn't "dual-life" -- |
3b4ebcde JV |
530 | it doesn't need to fully describe how all old versions used to work. |
531 | ||
17c80487 RS |
532 | =head1 STANDARDS OF CONDUCT |
533 | ||
534 | The official forum for the development of perl is the perl5-porters mailing | |
535 | list, mentioned above, and its bugtracker at rt.perl.org. All participants in | |
536 | discussion there are expected to adhere to a standard of conduct. | |
537 | ||
538 | =over 4 | |
539 | ||
540 | =item * | |
541 | ||
542 | Always be civil. | |
543 | ||
544 | =item * | |
545 | ||
546 | Heed the moderators. | |
547 | ||
548 | =back | |
549 | ||
550 | Civility is simple: stick to the facts while avoiding demeaning remarks and | |
551 | sarcasm. It is not enough to be factual. You must also be civil. Responding | |
552 | in kind to incivility is not acceptable. | |
553 | ||
8764ee63 CB |
554 | While civility is required, kindness is encouraged; if you have any doubt about |
555 | whether you are being civil, simply ask yourself, "Am I being kind?" and aspire | |
556 | to that. | |
557 | ||
17c80487 | 558 | If the list moderators tell you that you are not being civil, carefully |
8764ee63 CB |
559 | consider how your words have appeared before responding in any way. Were they |
560 | kind? You may protest, but repeated protest in the face of a repeatedly | |
561 | reaffirmed decision is not acceptable. | |
17c80487 RS |
562 | |
563 | Unacceptable behavior will result in a public and clearly identified warning. | |
522c63f2 RS |
564 | Repeated unacceptable behavior will result in removal from the mailing list and |
565 | revocation of rights to update rt.perl.org. The first removal is for one | |
566 | month. Subsequent removals will double in length. After six months with no | |
567 | warning, a user's ban length is reset. Removals, like warnings, are public. | |
17c80487 | 568 | |
0c6082f4 RS |
569 | The list of moderators will be public knowledge. At present, it is: |
570 | Aaron Crane, Andy Dougherty, Ricardo Signes, Steffen Müller. | |
3b4ebcde | 571 | |
48cb5b3a JV |
572 | =head1 CREDITS |
573 | ||
3b4ebcde | 574 | "Social Contract about Contributed Modules" originally by Russ Allbery E<lt>rra@stanford.eduE<gt> and the perl5-porters. |
3c78fafa | 575 |