├── README.md
├── berlin-consensus.md
├── cpan-common.md
├── cpan-packaging.md
├── lancaster-consensus.md
├── lyon-amendment.md
├── lyon-compromise.md
└── oslo-consensus.md
/README.md:
--------------------------------------------------------------------------------
1 | toolchain-site
2 | ==============
3 |
4 | This repo is for Perl toolchain docs, specs, guidelines, etc.
5 |
6 | A lot of this information is scattered across blogs, sites, repos,
7 | modules, etc. Some of it is ephemeral. This repo is intended to
8 | pull it together or provide authoritiative pointers.
9 |
10 | Initially, we'll dump docs here. Down the line, we should use
11 | github pages to create a site to serve it up.
12 |
13 |
--------------------------------------------------------------------------------
/berlin-consensus.md:
--------------------------------------------------------------------------------
1 | # The Berlin Consensus
2 |
3 | At the first Perl QA Hackathon (QAH) in 2008 in Oslo, a number of QA and
4 | toolchain authors, maintainers and experts came together to agree on some
5 | common standards and practices. This became known as
6 | ["The Oslo Consensus"](oslo-consensus.md).
7 |
8 | At the 2013 QAH in Lancaster, a similar brain trust came together to
9 | address new issues requiring consensus. This became known as
10 | ["The Lancaster Consensus"](lancaster-consensus.md).
11 |
12 | At the 2015 QAH in Berlin, another group assembled to address new issues,
13 | with a particular focus on toolchain governance and recommended standards
14 | of care for CPAN authors.
15 |
16 | As with other consensus discussions, the speed of implementation of any
17 | ideas discussed will depend on the interests and availability of volunteers
18 | to do the work.
19 |
20 | ## CPAN standards of care
21 |
22 | An ongoing challenge for Perl (and many other languages) is how to balance
23 | the benefits of a large repository of open source libraries (i.e. CPAN)
24 | against the fragility of large dependency trees. The consensus discussion
25 | group agreed on some recommended practices for CPAN authors that will, if
26 | widely adopted, improve the general standard of care of CPAN distributions
27 | and reduce the fragility of large CPAN dependency trees.
28 |
29 | ### The river analogy
30 |
31 | As an analogy to guide recommendations, the group considered CPAN like a
32 | "river". Distributions with nothing depending on them are all the way
33 | "downriver". Once a distribution gains a dependent, it moves slightly
34 | "upriver".
35 |
36 | Distributions can have *direct* dependents — things that list it among
37 | prerequisites — but direct dependents may have dependents, too, all the way
38 | down to distributions with no dependents at all.
39 |
40 | By examining this *deep dependent tree* to find the *total* number of
41 | downriver dependents, we can assess how far "up the river" anything is,
42 | which is tantamount to describing how many things it has the potential to
43 | break.
44 |
45 | As distributions have more and more total dependents in their deep
46 | dependent trees, the further upriver they are. All the way upriver lies
47 | the toolchain — modules like ExtUtils::MakeMaker, which, if buggy or
48 | broken, can break all of CPAN.
49 |
50 | Visually, if a module upriver breaks — fails to build, fails tests, breaks
51 | compatibility, etc. — it pollutes the river and everything downriver of it
52 | suffers.
53 |
54 | Therefore, a distribution's position in the river is a guide to the
55 | recommended standards that an author should apply to its care.
56 |
57 | As a distribution grows in popularity and gains direct dependents, those
58 | dependents grow the deep dependent tree; the distribution moves upriver and
59 | the standards that responsible authors should apply change accordingly.
60 |
61 | Authors, who could have distributions at multiple places along the river,
62 | should consider distributions individually, and avoid applying downriver
63 | standards to distributions that have moved upriver.
64 |
65 | The group also discussed how we never know how much of DarkPAN code depends
66 | on a given distribution, making any CPAN-focused analysis of the river only
67 | an approximation of the true number of downriver dependents.
68 |
69 | ### Recommended practices for CPAN authors
70 |
71 | For the sake of discussion, the group arbitrarily divided the river into
72 | "way downriver", "way upriver" and "in the middle", and considered
73 | recommended practices for each.
74 |
75 | While it wasn't discussed at the time, subsequent analysis found:
76 |
77 | * ~50 distributions with 10,000 or more total dependents
78 | * ~200 distributions with 1000 to 9,999 total dependents
79 | * ~2,000 distributions with 10 to 999 total dependents
80 | * ~8,000 distributions with 1 to 9 total dependents
81 | * ~16,000 distributions with no known dependents
82 |
83 | Again, while it wasn't discussed, if one needed guidance about whether a
84 | distribution is upriver or downriver or in the middle, one might consider
85 | the three groups roughly like this:
86 |
87 | * "way downriver" — zero to low tens of total dependents
88 | * "in the middle" — high tens to low thousands of total dependents
89 | * "way upriver" — high thousands to tens of thousands of total dependents
90 |
91 | The recommendations that follow for these groups are aspirational. Not
92 | every distribution can or will do everything here, but the more it can, the
93 | better off users of that distribution will be.
94 |
95 | #### Practices for distributions "way downriver"
96 |
97 | Any author's first upload is, by definition, way downriver. Brand new CPAN
98 | authors should read a good "how to" for CPAN authorship, such as
99 | the "About PAUSE" pages and "perldoc perlnewmod".
100 |
101 | Downriver distributions should be "well-formed", following many of the
102 | basic ["Kwalitee" rules](http://cpants.cpanauthors.org/kwalitee) described
103 | on CPANTS. They should have documentation (ideally spell-checked), a "t/"
104 | directory with tests (that are run before shipping, e.g. with "make
105 | disttest"), and a clearly stated license.
106 |
107 | Distributions should respect CPAN namespace conventions.
108 |
109 | Distributions should include a "Changes" file that highlights key
110 | differences between releases. They should have a META.json file that
111 | follows the CPAN::Meta::Spec and a
113 | corresponding META.yml file for older perls.
114 |
115 | The author should decide on an "issue tracker", whether the default
116 | rt.cpan.org or an issue tracker combined with a source code repository and
117 | include the issue tracker URL in the META.json file. Distribution
118 | documentation should include contact information if it differs from the
119 | author's cpan.org email address.
120 |
121 | If a distribution duplicates features of existing modules, the
122 | documentation should describe why it was created and how it differs from
123 | other, similar modules (e.g. a "SEE ALSO" section).
124 |
125 | There are also some practices that distributions should avoid.
126 |
127 | When configuring, building, testing or installing: don't attempt to "phone
128 | home" over the Internet; don't modify the filesystem outside the
129 | distribution directory or the system temporary directory; don't send
130 | emails.
131 |
132 | Don't hijack other modules by installing a .pm file that overwrites or
133 | otherwise shadows a module that ships from another distribution.
134 |
135 | Don't run "author tests" (e.g. pod formatting, coverage, spelling, etc.)
136 | on end-user systems.
137 |
138 | Don't be malicious.
139 |
140 | Don't be rude.
141 |
142 | #### Practices for distributions "in the middle"
143 |
144 | Distributions "in the middle" should follow all the recommendations of
145 | those "way downriver", plus additional recommendations.
146 |
147 | Distributions should plan for API stability. Breaking changes should
148 | be made as rarely as possible and should occur after a period of
149 | deprecation. Including a statement about a stability policy in
150 | documentation is recommended as well, to help end-users know what to
151 | expect.
152 |
153 | Distributions should aim to be portable across "mainstream" operating
154 | systems, whenever possible. They should attempt to support older Perls
155 | (e.g. 5.8 or 5.10) and should, regardless, have an explicit minimum perl
156 | version in their prerequisite metadata. Portability commitments should
157 | also be included in documentation.
158 |
159 | Distributions should have a public source code repository (listed in the
160 | META files), including contribution instructions. Repositories should be
161 | connected to some sort of [continuous integration service](https://encrypted.google.com/search?hl=en&q=free%20hosted%20continuous%20integration)
162 | for early identification of commits that cause tests to fail.
163 |
164 | Distributions should be licensed under the terms of Perl itself or else a
165 | compatible [OSI-approved license](http://opensource.org/licenses/). E.g. a
166 | GPL-only (or other "viral" license) may limit how far upriver a
167 | distribution can go. Note, also, that a "public domain" dedication is
168 | [not always legally valid](https://en.wikipedia.org/wiki/Public_domain#Dedicating_works_to_the_public_domain)
169 | and is not an OSI-approved license.
170 |
171 | Distribution authors should pay attention to the issue tracker and
172 | at least acknowledge bug reports in a timely fashion.
173 |
174 | Distributions should have a co-maintainer registered on PAUSE or other
175 | documented succession plan in case something happens to the original author.
176 |
177 | Distributions should aim for high quality releases: they should have good
178 | test coverage; authors should use author-only tests of distribution quality
179 | before shipping (e.g. in xt); authors should monitor CPAN Testers results
180 | to identify and fix broken releases.
181 |
182 | Before releasing a stable, indexed version to CPAN, authors should release
183 | a non-indexed, developer release to CPAN and monitor the [CPAN Testers
184 | Matrix](http://matrix.cpantesters.org/) results to ensure that nothing is broken
185 | across major operating systems or versions of Perl. (N.B. typically 36 to 48
186 | hours is sufficient for good coverage.)
187 |
188 | Distribution authors should be mindful of a distribution's place in the
189 | "CPAN river". They should pay attention to the stability and quality of
190 | upriver dependencies and should consider the stability and quality of a
191 | distribution before adding it as a new dependency. They should monitor the
192 | total number of downriver dependents to reassess the standards of care to apply
193 | to the distribution.
194 |
195 | For distributions in the upper-middle parts of the CPAN river (e.g. 1000+
196 | total downriver dependents), authors should consider regular testing of
197 | some or these downriver dependents against new versions of the distribution
198 | before shipping a stable release.
199 |
200 | #### Practices for distributions "way upriver"
201 |
202 | Distributions "way upriver", should follow all the recommendations of
203 | those "in the middle" and "way downriver", plus additional
204 | recommendations.
205 |
206 | Distributions should undergo some sort of code review before a stable
207 | release, so that there is more than one set of eyes responsible for the
208 | code.
209 |
210 | Distributions should have some documented public forum for discussing
211 | the distribution and its evolution. Proposed major changes should be
212 | discussed before implementation.
213 |
214 | Distributions should design for forward-compatibility, when possible,
215 | so that old code can handle inputs designed for later versions of the
216 | distribution and either adapt or throw an informative error, rather than
217 | fail strangely.
218 |
219 | Distributions that use C or XS should aim for C89 compatibility, the same
220 | as Perl itself.
221 |
222 | Distributions should do performance testing before releasing major changes
223 | as stable.
224 |
225 | Distributions should be tested against bleadperl, on as many platforms as
226 | they can.
227 |
228 | Authors should release a non-indexed development version of distributions
229 | before an indexed, stable version for any non-trivial, non-emergency
230 | change.
231 |
232 | Authors should regularly check the full [CPAN testers
233 | matrix](http://matrix.cpantesters.org/) for distributions to find failure
234 | patterns that affect particular platforms or versions of Perl.
235 |
236 | Authors should test at least a representative portion of direct (or even
237 | total) downriver dependents against new versions of a distribution before
238 | shipping a stable release.
239 |
240 | Stable releases of distributions should not be shipped before bedtime or
241 | the weekend or any other time when the author is unavailable to fix or
242 | revert an unexpectedly broken release. Authors should watch closely for
243 | indications of breakage after release.
244 |
245 | ### Responsible forking
246 |
247 | While we hope that authors follow standards of care consistent with a
248 | distribution's place in the CPAN river, there will always be times when
249 | some distribution dependency isn't meeting one's expectations. In such a
250 | case, a distribution always has the option to fork the dependency or to
251 | replace it with an alternative.
252 |
253 | Because forks can be controversial, we discussed practices for responsible
254 | forking.
255 |
256 | When this section talks about "forks", we intend that term to cover
257 | literal forks (same code base to start, and same API), rewrites (new code
258 | base, but same API) and alternative replacements (new code, with new API).
259 |
260 | #### Before forking
261 |
262 | Before considering a fork, authors should talk to the current maintainer(s)
263 | about their concerns, ideally in a public forum so that concerns and
264 | responses are on the record.
265 |
266 | Authors should also consult interested parties, such as other authors with
267 | similar concerns (e.g. authors of other distributions who also depend on
268 | the distribution to be forked, as well as direct downriver dependents who
269 | might be affected by the change in their own upriver dependency tree.
270 |
271 | #### When deciding to fork
272 |
273 | If the original maintainer isn't able to satisfy concerns and the decision
274 | to fork is taken, authors should notify the original maintainer(s), again
275 | ideally in a public forum so that the history is available for future users
276 | to review.
277 |
278 | The author should also notify interested parties that were consulted, so
279 | that they can participate in the process, if desired.
280 |
281 | To help future potential users understand the differences between the
282 | modules, the author should document the rationale for forking (focusing on
283 | factual rather than emotional issues or personal attacks).
284 |
285 | Authors should try not to "burn bridges". On seeing a fork under
286 | development, the original maintainer may reconsider his or her original
287 | stance, or offer to hand over maintenance or otherwise find some
288 | mutually satisfactory resolution that doesn't require the fork to be
289 | published to CPAN.
290 |
291 | #### After a fork is published
292 |
293 | When the fork is shipped, the author should make a general announcement to
294 | the same forums used for earlier discussions.
295 |
296 | The author should carefully consider impacts on the CPAN river when
297 | migrating. E.g. adding a newly published fork as the dependency of a
298 | mid-stream distribution catapults the fork upriver, which adds it as a
299 | dependency to all downriver distributions and puts them all at risk
300 | if the fork introduces new bugs or other surprising behavior.
301 |
302 | When considering urging other distributions to adopt a fork in place of the
303 | original, authors should use a "smart bomb" approach rather than a "carpet
304 | bomb" approach. Rather than making an appeal to all direct dependents of the
305 | original, authors should target the appeal. Examples of respectful
306 | targeting include (but are not limited to):
307 |
308 | * upriver dependencies that also depend on the original distribution (e.g.
309 | as part of an attempt getting the original out of the full upriver
310 | dependency tree)
311 | * other, unrelated distributions that are reasonably believed to be
312 | affected by the same issues that prompted the fork
313 |
314 | ## Toolchain governance
315 |
316 | The toolchain, in general terms, refers to those modules that are required
317 | to download, build, test and install the vast majority of
318 | distributions on CPAN.
319 |
320 | Modules like this generally ship with the Perl core (e.g.
321 | ExtUtils::MakeMaker) but frequently have a "dual life" independently on
322 | CPAN. By definition, these toolchain distributions are "way upriver" on
323 | the CPAN river.
324 |
325 | Other modules may not ship in the Perl core, but may be popular solutions
326 | for specific toolchain-like tasks. Such modules are in the "toolchain"
327 | for distributions that rely on them.
328 |
329 | The consensus attendees represented a sizeable cross-section of core and
330 | popular non-core toolchain maintainers. They agreed that toolchain
331 | development and release practices could be improved.
332 |
333 | They agreed to "sign on" to a "Toolchain Charter" to govern the ongoing
334 | development of toolchain distributions. While this discussion actually
335 | pre-dated the CPAN river discussion, the points are largely consistent.
336 |
337 | ### Toolchain charter practices
338 |
339 | Toolchain authors present agreed to the following principles and practices
340 | to ensure good governance and responsible administration.
341 |
342 | 1. The toolchain has a wider scope of backwards compatibility goals than
343 | the Perl core, as toolchain aims to support every Perl from 5.8.1
344 | onwards.
345 |
346 | 2. Toolchain distributions should have more than one "primary" maintainer
347 | (regardless of actual PAUSE permissions) and a list should be published
348 | showing distributions and maintainers.
349 |
350 | 3. Functional changes to toolchain distributions need more than one set of
351 | eyes approving changes before shipping a stable release to CPAN
352 |
353 | 4. Major or breaking changes to a toolchain distribution should be
354 | discussed in a public, archived venue. The
355 | [cpan-workers](http://lists.perl.org/list/cpan-workers.html) list was
356 | chosen as the initial venue.
357 |
358 | 5. If discussions about the evolution of toolchain distributions fail to
359 | achieve consensus, toolchain authors agree to defer to a designated
360 | "tie-breaker" authority. The Perl pumpking (regardless of who that may
361 | be at any point in time) was the initial choice for tie-breaker.
362 |
363 | 6. No stable distribution should ship until some degree of stability is
364 | verified (e.g. though a combination of smoke reports, dependency smokes,
365 | etc.); the choice of specific mechanisms were left to the discretion of
366 | maintainers. The group called out one exception: emergency fixes to a
367 | broken stable release should proceed without delay.
368 |
369 | 7. Toolchain authors agreed that when a primary maintainer steps down or
370 | becomes permanently unavailable, the toolchain authors as a group will
371 | jointly agree on a successor. PAUSE administrators should defer to the
372 | consensus (or decision of the tie-breaker) for handing over PAUSE
373 | permissions as needed. Any successor should agree to the practices
374 | described herein.
375 |
376 | Toolchain authors not present are strongly encouraged to agree to these
377 | practices or to hand over their toolchain maintenance responsibilities to
378 | others who are willing to do so.
379 |
380 | ### Model behavior we want to see in other "way upriver" distributions
381 |
382 | The group briefly discussed whether or how to urge other important,
383 | non-toolchain, but widely depended-on distributions to sign on to the
384 | Toolchain Charter or an equivalent.
385 |
386 | The consensus was that the Toolchain Charter should serve as a model for
387 | the kind of behavior we'd like to see broadly in other widely used
388 | distributions, but that public role-modeling and public promotion was
389 | preferred over targeted appeals or peer pressure on non-toolchain authors.
390 |
391 | ## META spec
392 |
393 | The group discussed various potential changes to the [CPAN META
394 | Spec](http://p3rl.org/CPAN::Meta::Spec).
395 |
396 | ### No need for META 3 yet
397 |
398 | There was consensus that developing a "v3" META spec was not yet needed.
399 | There was no burning platform for it, and some forward compatibility risks
400 | to address first. The consensus was that continuing to develop
401 | `x_` fields was sufficient to address emerging needs.
402 |
403 | ### prereqs keys to ignore
404 |
405 | The 'prereqs' data structure can contain fields that can't be resolved as
406 | actual prerequisites. Examples include "perl", "Config" and "Errno". The
407 | group agreed that a list of known keys should be included in the
408 | implementation notes section of the META spec.
409 |
410 | Specifically with regards to 'perl', we agreed that CPAN clients must never
411 | try to install 'perl'. If it is specified as 'requires', installation must
412 | abort. If specified for 'recommends' or 'suggests', CPAN clients may warn
413 | about it, but must otherwise ignore it.
414 |
415 | ### Further clarifying 'recommends' and 'suggests'
416 |
417 | The group agreed that these prerequisite relationships were still being
418 | misunderstood and that the spec should be clear that "recommends" is
419 | optional and installed by default, whereas "suggests" is optional and not
420 | installed by default.
421 |
422 | ### CPAN client interpretation of 'x_breaks'
423 |
424 | The group agreed that `x_breaks` needs to be implemented in CPAN clients.
425 |
426 | `x_breaks` is a top-level key in META. It is a hash with module
427 | name as keys and a version range that indicates the *broken* range, usually
428 | using as a `<=` relation. E.g. in YAML format:
429 |
430 | x_breaks:
431 | Foo::Bar: <= 1.23
432 |
433 | When `x_breaks` is found in MYMETA or META, after successful installation,
434 | CPAN clients should check if any of the modules listed in `x_breaks` are
435 | installed and if their `$VERSION` matches the version range. If so, and if
436 | the latest version on CPAN does *not* match the `x_breaks` version range,
437 | then the CPAN client should install the latest version of that module from
438 | CPAN
439 |
440 | CPAN clients may warn about unsatisfiable `x_breaks` before or after
441 | installing a module, may prompt before installing `x_breaks`, etc.,
442 | depending on their individual approaches to configuration, prompting and
443 | warning.
444 |
445 | ### Need for a post-install recommendations key
446 |
447 | There are circumstances where two distributions can each operate without
448 | the other but both benefit from the other's presence. In this case, each
449 | specifying the other as 'recommended' causes a circular dependency, albeit
450 | an optional one, which can confuse CPAN clients and dependency analysis.
451 |
452 | To avoid this, the group agreed there needs to be a new META key that
453 | requests that CPAN clients install a distribution after installation is
454 | complete — not a prerequisite relationship, but an "also install"
455 | relationship.
456 |
457 | We agreed that Karen Etheridge volunteered to prototype such a key and discuss it
458 | with CPAN client authors for feedback and potential implementation.
459 |
460 | ## Signaling pure-Perl
461 |
462 | In the Lancaster Consensus, the group agreed on command-line arguments for
463 | Makefile.PL and Build.PL to signal that a pure-Perl build is desired. In
464 | practice, the problem with this approach is that distribution authors must
465 | each individually check for such flags and take them into account.
466 |
467 | The group agreed that since there are relatively few compiler-detectors
468 | (e.g. ExtUtils::CBuilder), it would be better to have a common environment
469 | variable that signals to such compiler detectors to report that no compiler
470 | is available. This would then have an effect on all distributions using
471 | that compiler detector.
472 |
473 | Peter Rabbitson volunteered to pick a name for the variable and Leon
474 | Timmermans agreed to implement it in ExtUtils::CBuilder.
475 |
476 | ## CPAN Testers grading
477 |
478 | The historical policy of CPAN Testers was to not send failing test reports
479 | when prerequisites could not be satisfied. The group agreed that getting
480 | such reports – under some other category than "FAIL" — would make it easier
481 | to detect when upriver dependencies were broken.
482 |
483 | Barbie and David Golden volunteered to come up with a proposal for review
484 | on the cpan-workers list.
485 |
486 | ## PAUSE
487 |
488 | The group considered potential changes to PAUSE administration and
489 | policies.
490 |
491 | ### Changing adoption policies
492 |
493 | Historically, the process for adopting an abandoned distribution allowed
494 | the first person to petition PAUSE admins for a takeover to receive
495 | permissions. In light of concerns about the stability of distributions
496 | with lots of downriver dependencies, the group thought a policy of
497 | "first warm body" adoption was no longer a wise idea.
498 |
499 | The group considered the opposite approach — that PAUSE admins no longer
500 | transfer permissions at all; that if the primary maintainer were gone,
501 | that a distribution was effectively end-of-life. The group agreed that
502 | this would do more harm than good.
503 |
504 | The group agreed that for distributions with no known dependencies, the
505 | "first warm body" rule was acceptable. For distributions with
506 | dependencies, PAUSE administrators will consider the number of downriver
507 | dependencies and exercise their judgment and consider the track record and
508 | involvement of a petitioner in the distribution in question. E.g. they will
509 | consider existing co-maintainer status, commit involvement, etc. Without
510 | obvious involvement of this sort, a petitioner will need to present some
511 | evidence of support from interested parties (e.g. direct downriver dependents).
512 |
513 | PAUSE administrators may elect to deliberate on their decision in private,
514 | but will announce a decision and rationale publicly.
515 |
516 | Distributions that want to avoid succession problems are encouraged to
517 | add co-maintainers as designated successors.
518 |
519 | ### Rewriting PAUSE not needed
520 |
521 | The group considered briefly whether PAUSE needed to be rewritten from
522 | scratch. The consensus was to proceed with efforts to Plack-ify it
523 | and use that as a basis for additional development.
524 |
525 | ### Encouraging good licensing
526 |
527 | The group considered whether PAUSE should require a detectable license
528 | for indexing; instead the group decided that authors should be encouraged,
529 | but not required, to have one. E.g. the indexer email could notify authors
530 | that no license was found and encourage them to add one.
531 |
532 | ### Responding to take-down requests
533 |
534 | We discussed whether PAUSE should have a formal policy about take-down
535 | requests. The consensus was that it was unnecessary and that instead,
536 | PAUSE admins will continue to exercise judgment.
537 |
538 | However, we agreed that PAUSE (and all other Perl ecosystem sites) should
539 | have clearly indicated contact information for take-down notices.
540 |
541 | ### Deleting tarballs faster
542 |
543 | Currently, deleting a tarball on PAUSE schedules it for deletion in three
544 | days. We agreed that faster – nearly immediate – deletion is desirable to
545 | get broken distributions off CPAN quickly.
546 |
547 | However, we agreed there should be a slight delay to give backpan mirrors a
548 | chance to catch up to store the distribution for the historical record.
549 |
550 | Any such feature requires some sort of confirmation to help users avoid
551 | deleting things unintentionally.
552 | [Issue #163](https://github.com/andk/pause/issues/163) has been opened for this
553 | feature request.
554 |
555 | ### Requiring a meta file to be indexed
556 |
557 | The group discussed whether PAUSE should require a valid META file for a
558 | distribution to be indexed. When META generators start universally
559 | providing the 'provides' field, this will get PAUSE out of the business of
560 | guessing which packages are provided by a distribution, so encouraging
561 | including META now will lay the groundwork for that future change.
562 |
563 | If implemented, distributions would be required to have either META.json or
564 | META.yml to be indexed.
565 |
566 | The group thought this seemed reasonable, but there was some concern about
567 | how many distributions in the recent past would have had problems if this
568 | the policy had been in force. Ricardo Signes volunteered to research how
569 | many distributions uploaded recently would have had problems and review
570 | with Andreas Koenig before implementing.
571 |
572 | ## Test-Simple roadmap
573 |
574 | As part of the consensus discussions, the group considered the roadmap
575 | for Test-Simple which provides the Test::Builder library upon which
576 | Test::More and most test libraries are written.
577 |
578 | ### Problems in Test::Builder
579 |
580 | The group identified several fundamental limitations of Test::Builder:
581 |
582 | * Async/multi-process support is either non-existent or requires complex
583 | and fragile work-arounds.
584 | * The lack of extension points has led many test libraries to invade the
585 | private internals of the Test::Builder singleton, or to monkey-patch its
586 | methods. These hacks are inherently fragile and the more the test
587 | ecosystem proliferates such things, the more likelihood that mixing
588 | arbitrary test libraries will break in unexpected ways.
589 | * Testing test libraries requires either parsing TAP or checking against
590 | specific strings. This is hard, leaving many test libraries poorly
591 | tested, if at all. When there are tests, the tests are fragile. Overall,
592 | this limits the ability of test library authors to evolve TAP itself.
593 | * More generally, having the test library so tightly coupled to TAP means
594 | that the capabilities of the library are limited to what TAP supports and
595 | there's no easy way to use the standard testing library, but output
596 | results in a different form (e.g. xUnit-style).
597 | * The current Test::Builder is heavy and slow, holding too much state and
598 | doing to much repetitive work.
599 |
600 | ### Cost, benefits and risks
601 |
602 | The group judged the benefit of addressing the problems above to
603 | significant enough to justify the idea of a rewrite of the internals of
604 | Test::Builder.
605 |
606 | With regard to the proposed Test::Stream-based replacement, the group
607 | agreed that the general design could address some of the problems
608 | identified, but, in light of the risks, put forth a "punchlist" of specific
609 | tasks to be completed before considering the specific implementation of
610 | that design ready to move forward:
611 |
612 | * A single Test-Simple branch with proposed code and a corresponding
613 | Test-Simple dev release to CPAN
614 | * Single document describing all known issues
615 | * Invite people to install latest dev in their daily perls for feedback
616 | * Write document explaining how to do so and how to roll-back
617 | * Update CPAN delta smokes: compare test results for all of CPAN with
618 | latest Test-Simple stable and latest
619 | * On Perl versions 5.8.1 and 5.20.2; both with and without threads
620 | * Finding no new changes from previous list of incompatible modules doing
621 | unsupported things
622 | * Line-by-line review of $Test::Builder::Level back compatibility support
623 | * bleadperl delta smoke with verbose harness output with latest stable and
624 | latest dev; review line-by-line diff and find no substantive changes
625 | (outside Test-Simple tests themselves)
626 | * Performance benchmarking — while specific workloads will vary, generally
627 | a ~15% slowdown on a "typical" workload is acceptable if it delivers the
628 | other desired benefits.
629 | * Add patches to existing benchmarking tools in Test-Simple repo
630 | * Run benchmarks on at least Linux and Windows
631 |
632 | The group agreed that additional items could be added through the toolchain
633 | governance mechanism.
634 |
635 | ## Participants in the Berlin Consensus discussions
636 |
637 | Discussions lasted over 4 days, participants came and went, but each day
638 | had about 20-25 people. Thank you to the following participants:
639 |
640 | Andreas König, Aristotle Pagaltzis, Barbie, Bulk88, Chad Granum, David
641 | Golden, H. Merijn Brand, Helmut Wollmersdorfer, Herbert Breunung, Ingy döt
642 | Net, Karen Etheridge, Kenichi Ishigaki, Leon Timmermans, Matthew Horsfall,
643 | Neil Bowers, Olivier Mengué, Paul Johnson, Peter Rabbitson, Philippe
644 | Bruhat, Ricardo Signes, Salve J. Nilsen, Slaven Rezic, Stefan Seifert,
645 | Tatsuhiko Miyagawa, Tina Müller, and Wendy van Dijk
646 |
647 | (Apologies to anyone present who was left off the list. Email dagolden at
648 | cpan dot org or send a pull request to be added.)
649 |
650 | ## Copyright and License
651 |
652 | This document is Copyright 2015 by David A. Golden and contributors. You
653 | can redistribute it and/or modify it under the same terms as the Perl 5
654 | programming language system itself.
655 |
--------------------------------------------------------------------------------
/cpan-common.md:
--------------------------------------------------------------------------------
1 | # conceptual CPAN pipeline
2 |
3 | $ cpan-lookup Foo::Bar => JDOE/Foo-Bar-1.23.tar.gz
4 |
5 | $ cpan-get JDOE/Foo-Bar-1.23.tar.gz => /tmp/Foo-Bar-1.23.tar.gz
6 |
7 | $ cpan-expand $tmp_tarball => setup dir
8 |
9 | $ cpan-configure $tmp_dir => MYMETA.json
10 |
11 | $ cpan-prereqs --missing MYMETA.json => @modules/@dists XXX
12 |
13 | $ cpan-build $tmp_dir => $tmp_dir
14 |
15 | $ cpan-test $tmp_dir => $tmp_dir
16 |
17 | $ cpan-stage $tmp_dir => $tmp_dir
18 | (install into $stage/phase/type/blib/... ?!)
19 |
20 | $ cpan-install $phase $type
21 | (can't take just from XXX ?)
22 | things might have custom installation XXX
23 |
24 | Stage: core vs. site vs. vendor vs. local::lib (all possible at once?)
25 |
26 |
27 | # CPAN::Context
28 |
29 | * hold + dispatch to objects?
30 | * or retrieve objects?
31 |
32 | Q: what's the necessary context needed by Distribution object
33 |
34 | * feedback callbacks on progress
35 | * depends how much Distributions process dependency resolution process vs. rely on external query XXX
36 |
37 |
38 | # cpan> install Foo::Bar
39 |
40 | 1. request install for Foo::Bar [Queue]
41 |
42 | 2. resolve Foo::Bar to LOCAL/Foo-Bar-1.23.tar.gz [Index]
43 |
44 | 3. Check if L/FB exists in Dist Obj Cache [Session]
45 |
46 | (if so, get it + jump to 8)
47 |
48 | 4. get L/FB fron a CPAN mirror to a local cache [Client]
49 |
50 | 5. uncompress it to a directory [TarZip]
51 |
52 | 6. create DistObject [Dist]
53 |
54 | 7. register DistObject in cache [Session]
55 |
56 | 8. check config-requires [Dist]
57 |
58 | if no config-requires, jump to ...
59 |
--------------------------------------------------------------------------------
/cpan-packaging.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | This document provides guidelines for various aspects of packaging modules on CPAN into operating system packages, to be distributed and installed independent of CPAN. As such this is directed at operating system packagers, to explain what they should expect to recieve from CPAN and how to interact with it. Most of this information is also available elsewhere, but not in one place. The other documents in this repository provide further details on many aspects of it.
4 |
5 | # Build phases
6 |
7 | The installation process of a CPAN module goes through four sequential phases:
8 |
9 | ## Configure
10 |
11 | Expectations before running the configure phase:
12 |
13 | 1. A Makefile.PL and/or Build.PL file is present
14 | 2. A META.json and/or META.yml file is present
15 |
16 | Expectations after the configuration phase if successful:
17 |
18 | 1. A Makefile or Build file is present
19 | 2. A MYMETA.json and/or MYMETA.yml file is present
20 |
21 |
22 | ## Build
23 |
24 | Before running this phase, the configure phase **must** have been successfully completed.
25 |
26 | This phase is expected to do everything needed before the distribution can be tested and/or installed.
27 |
28 |
29 | ## Test
30 |
31 | Before running this phase, the build phase **must** have been successfully completed. This phase is technically optional, but highly recommended. This phase will run all tests, and report success or failure.
32 |
33 |
34 | ## Install
35 |
36 | Before running this phase, the build phase **must** have been successfully completed. This will install the distribution files to the designated location.
37 |
38 |
39 | # Meta files
40 |
41 | There are two active versions of the meta file specification: [2.0](https://metacpan.org/pod/CPAN::Meta::Spec), stored in META.json; and [1.4](https://metacpan.org/dist/CPAN-Meta/view/lib/CPAN/Meta/History/Meta_1_4.pod), stored in META.yml. Consumers **must** prefer the former over the latter if both exist. It is recommended to use CPAN::Meta to interact with these files, as it can automatically upconvert 1.4 to 2.0.
42 |
43 | There are two stages of these files: META.json and MYMETA.json. META.json is generated by the authoring tool, and is authoritative on all metadata except non-configure prerequisites. MYMETA.json is generated during the configuration, and is the authoritative source for all other prerequisites. If and only if the `dynamic_config` entry in the META.json file is set to `0`, META and MYMETA will be identical and all META prereqs **may** be treated as authoritative.
44 |
45 |
46 | ## Prerequisite phases
47 |
48 | As defined in the Meta 2.0 specification, there are four prerequisite phases for dependencies on other CPAN modules:
49 |
50 |
51 | ### Configure
52 |
53 | These dependencies **must** be available before even trying to configure the distribution and **must** remain available until the install phase is finished; they are not required to be available after install. These are usually the only requirements that should be taken from the META.json file. Typically this would be the install tool (e.g. Module::Build or Module::Build::Tiny) and may be empty (e.g. when using ExtUtils::MakeMaker).
54 |
55 | If only a Build.PL file is available (no Makefile.PL), and the configure requirements are empty, packages **should** inject Module::Build as an implicit dependency.
56 |
57 |
58 | ### Build
59 |
60 | These **must** be available before entering the build phase and should remain available until the install phase is finished; they are not required to be available after install. Typically this would be empty.
61 |
62 |
63 | ### Test
64 |
65 | These **must** be available before entering the test phase; they are not required to be available after testing. Typically this would include various modules such as Test::More or Test2::V0.
66 |
67 |
68 | ### Runtime
69 |
70 | These are only the dependencies that **must** be available when the install phase has finished; in a binary packaging system these are the only dependencies that need to be declared in the final package. They **must** be available before the build phase starts.
71 |
72 |
73 | ## Prerequisite relationships
74 |
75 | As defined in the Meta 2.0 specification, there are four relationship types for dependencies on other CPAN modules:
76 |
77 |
78 | ### Requires
79 |
80 | These dependencies **must** be installed for proper completion of the phase.
81 |
82 |
83 | ### Recommends
84 |
85 | Recommended dependencies are _strongly_ encouraged and should be satisfied except in resource constrained environments. All "must"s regarding the different phases mentioned above should be interpreted as "should".
86 |
87 | Experience has shown that recommendations sometimes include cyclical dependencies, these should be handled mindfully or else these are better skipped entirely.
88 |
89 |
90 | ### Suggests
91 |
92 | These dependencies are optional, but are suggested for enhanced operation of the described distribution.
93 |
94 | Like recommends, these are probably better skipped if the system can't handle cyclic dependencies.
95 |
96 |
97 | ### Conflicts
98 |
99 | These libraries cannot be installed when the phase is in operation. In practice this is not used as no CPAN client ever implemented it, so it can probably be ignored.
100 |
101 |
102 | # Perl Configuration
103 |
104 | The CPAN installation involves Perl's own configuration parameters. Most obviously the various arguments for setting the installation directories. It defines three types of install directories:
105 |
106 |
107 | ## Install Dirs
108 |
109 | ### core / perl
110 |
111 | This is where all modules that ship with perl itself are installed. Packagers should generally not install anything to this destination.
112 |
113 |
114 | ### vendor
115 |
116 | This is where vendor packages should go. This is not enabled by default because a local install doesn't need it, but for a distributor it's generally recommended to use this.
117 |
118 |
119 | ### site
120 |
121 | This is where users can install their own modules; typically this would be under /usr/local.
122 |
123 |
124 | ## Install categories
125 |
126 | For each of the three install dirs, six categories are installed that each have their own installation location.
127 |
128 |
129 | ### lib
130 |
131 | This is where pure-perl modules will be installed
132 |
133 |
134 | ### arch
135 |
136 | This is where perl modules with binary components will be installed
137 |
138 |
139 | ### script
140 |
141 | This is where executable scripts are installed
142 |
143 |
144 | ### bin
145 |
146 | This is where executable binaries are installed. Usually this is the same location as script
147 |
148 |
149 | ### man1
150 |
151 | This is where man pages for scripts and binaries are installed
152 |
153 |
154 | ### man3
155 |
156 | This is where man pages for libraries are installed
157 |
158 |
159 | # Install tool protocols
160 |
161 | There are three different protocols for installing. All of them follow the four build phases described above (configure, build, test, install)
162 |
163 |
164 | ### Makefile.PL
165 |
166 | This is the original protocol. It does not have a specification, but in practice is defined by the [ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils::MakeMaker) implementation. The four phases look like
167 |
168 | 1. perl Makefile.PL
169 |
170 | 2. make
171 |
172 | 3. make test
173 |
174 | 4. make install
175 |
176 |
177 | ### Build.PL
178 |
179 | This protocol originates in Module::Build, but now has more implementations. It is defined by the [Build.PL spec](https://metacpan.org/pod/CPAN::API::BuildPL) , and packages **should not** stray beyond the options defined by it (or request extending the spec with additional options). The four phases look like:
180 |
181 | 1. perl Build.PL
182 |
183 | 2. ./Build
184 |
185 | 3. ./Build test
186 |
187 | 4. ./Build install
188 |
189 | If both a Makefile.PL and Build.PL file are present, the packager **should** prefer the Build.PL file.
190 |
191 |
192 | ### Static install
193 |
194 | Packagers **may** use the [Static Install Spec](https://metacpan.org/pod/CPAN::Static::Spec) to install the distribution if the `x_static_install` entry in the META file is set to a supported version of the static install specification. In such a case, they **may** ignore the configure dependencies.
195 |
196 |
197 | ## Common arguments
198 |
199 | It is encouraged to pass all arguments at configuration time, even if it's often possible to do so in later stages. In practice, there are only a few types of arguments that should be common for packagers:
200 |
201 |
202 | ### Destdir
203 |
204 | The destdir is used to install all files to a staging directory, that is typically then tarred into a package. In Makefile.PL it's set using the DESTDIR argument (e.g. «perl Makefile.PL DESTDIR=/tmp/abcdef»), in Build.PL it's set using the --destdir argument (e.g. «perl Build.PL --destdir /tmp/abcdef»).
205 |
206 |
207 | ### Installdirs
208 |
209 | The installdir can be set to any of the three values mentioned in the "Install Dirs" section: 'perl' (Makefile.PL) / 'core' (Build.PL), 'vendor' or 'site' (default). This can be used to set the installdir type. Typically a packager would use «INSTALLDIRS=vendor» (Makefile.PL) or «--installdirs vendor» (Build.PL) to ensure the distribution is installed to the vendor paths.
210 |
211 |
212 | # Mapping dependencies
213 |
214 | On CPAN, dependencies are declared on modules, not on distributions. As such, any declared dependency should first be mapped from module to distribution, before it is mapped to the native package.
215 |
216 |
217 | # Versions
218 |
219 | Versions in Perl work a bit differently than in other systems. This can cause problems, especially when CPAN authors change their version scheme or length without understanding the consequences
220 |
221 | There are two types of versions in perl. Decimal versions, which work essentially as a normal number, and dotted decimal versions, which works more like one expects from semantic versions.
222 |
223 | Decimal versions acting like numbers means that the version "1.2" is equal to the versions "1.20" and "1.200". In practice that means that CPAN authors shortening their versions can break things for downstream vendors that use a more semantic versioning scheme.
224 |
225 | Dotted decimal is typically prefixed with a "v" e.g. "v1.2.3". They work by comparing each number sequentially. Unlike typical semantic versioning they null-extend much like decimals though ("v1.2.3" equals "v1.2.3.0").
226 |
227 | Decimals can be mapped to dotted-decimal by splitting them by 3 digits. So "1.2345" equals "v1.234.500". When using decimal versions, CPAN authors are [advised](https://blogs.perl.org/users/grinnz/2018/04/a-guide-to-versions-in-perl.html) to use a multiple of three digits, and when using dotted decimals to use the components in the 0-999 range.
228 |
229 | Development releases of CPAN modules can contain underscores. Generally speaking packages should not package such versions and as such these should not be their concern.
230 |
231 |
232 | # Licensing
233 |
234 | CPAN packages typically declare their license using the [`license`](https://metacpan.org/pod/CPAN::Meta::Spec#license) field of their meta files. They may also declare an SPDX expression in their `x_spdx_expression` field. If absent, the license may be derived from the LICENSE, COPYING or README file, or from the module's documentation.
235 |
236 |
237 | # Environmental variables
238 |
239 | ### `PERL_MM_USE_DEFAULT`
240 |
241 | If set to true, configure time prompts will always use the default value, even if its stdin is a tty.
242 |
243 | ### `AUTOMATED_TESTING`
244 |
245 | If true, tests are being run by an automated testing facility and not as part of the installation of a module.
246 |
247 | ### `EXTENDED_TESTING`
248 |
249 | If true, the user or process running tests is willing to run optional tests that may take extra time or resources to complete.
250 |
251 | ### `NO_NETWORK_TESTING`
252 |
253 | If true, this signals that tests requiring internet access should be skipped.
254 |
255 | ### `NONINTERACTIVE_TESTING`
256 |
257 | if true, tests should not attempt to interact with a user; output may not be seen and prompts will not be answered.
258 |
--------------------------------------------------------------------------------
/lancaster-consensus.md:
--------------------------------------------------------------------------------
1 | # The Lancaster Consensus
2 |
3 | At the first Perl QA Hackathon in 2008 in Oslo, a number of QA and
4 | toolchain authors, maintainers and experts came together to agree on some
5 | common standards and practices. This became known as
6 | ["The Oslo Consensus"](oslo-consensus.md).
7 |
8 | Five years later, at the 2013 Perl QA Hackathon, a similar brain trust came
9 | together to address new issues requiring consensus.
10 |
11 | These decisions provide direction, but, as always, the speed of
12 | implementation will depend on the interests and availability of volunteers
13 | to do the work.
14 |
15 | ## Toolchain and testing
16 |
17 | ### Minimum-supported Perl
18 |
19 | > 👉 This section is obsoleted by the [Lyon Amendment](lyon-amendment.md) to
20 | > the Lancaster Consensus. This replaces 5.8 with "ten years of versions",
21 | > roughly. See that document for more details.
22 |
23 | Going forward, the Perl toolchain will target Perl 5.8.1, released
24 | September 2003. This will allow toolchain modules to reliably use PerlIO
25 | and improved Unicode support.
26 |
27 | Because of the many Unicode bug-fixes in early 5.8 releases,
28 | toolchain maintainers reserve the right to later bump the
29 | minimum to 5.8.4 (which ships with Solaris 10).
30 |
31 | ### Specifying pure-perl builds
32 |
33 | Some distributions offer an "XS" version or a "Pure Perl" version that can
34 | be selected during configuration. Currently, each of these has their own
35 | way for users to indicate this, which makes it impossible for CPAN clients
36 | or other build tools to help users select automatically.
37 |
38 | Going forward, the "spec" for Makefile.PL and Build.PL will include command
39 | line options to request a "pure Perl only" build. These will be:
40 |
41 | * PUREPERL\_ONLY=1 (for Makefile.PL)
42 | * --pureperl-only (for Build.PL)
43 |
44 | These may be set in the `PERL_MM_OPT` or `PERL_MB_OPT` environment
45 | variables just like any other command line option.
46 |
47 | If present, distribution authors must ensure that the installed modules do
48 | not require loading XS (whether directly or via Inline) or dynamically
49 | generate any platform-specific code. The installed files must be able to
50 | run correctly if copied to another machine with the same Perl version but a
51 | different architecture (e.g. "fatpacking" an application). If this
52 | condition can not be met, configuration must exit with an error.
53 |
54 | ### Environment variables for testing contexts
55 |
56 | The Oslo Consensus defined two testing contexts: `AUTOMATED_TESTING` and
57 | `RELEASE_TESTING`. Of these, `AUTOMATED_TESTING` has been the most
58 | confusing, as it sometimes was used to mean "don't interact with a user"
59 | and sometimes "run lengthy tests".
60 |
61 | We also (briefly) discussed how some tools like Dist::Zilla are using
62 | `AUTHOR_TESTING` distinct from `RELEASE_TESTING`.
63 |
64 | Distribution authors should now follow these semantics:
65 |
66 | * `AUTOMATED_TESTING`: if true, tests are being run by an automated testing
67 | facility and not as part of the installation of a module; CPAN smokers
68 | must set this to true; CPAN clients must not set this
69 |
70 | * `NONINTERACTIVE_TESTING`: if true, tests should not attempt to interact
71 | with a user; output may not be seen and prompts will not be answered
72 |
73 | * `EXTENDED_TESTING`: if true, the user or process running tests is willing
74 | to run optional tests that may take extra time or resources to complete.
75 | Such tests must not include any development or QA tests. Only tests of
76 | runtime functionality should be included.
77 |
78 | * `RELEASE_TESTING`: if true, tests are being run as part of a release QA
79 | process; CPAN clients must not set this variable
80 |
81 | * `AUTHOR_TESTING`: if true, tests are being run as part of an author's
82 | personal development process; such tests may or may not be run prior to
83 | release. CPAN clients must not set this variable. Distribution
84 | packagers (ppm, deb, rpm, etc.) should not set this variable.
85 |
86 | There are already two libraries on CPAN to make it easier to test these
87 | variable correctly:
88 |
89 | * [Test::Is](http://p3rl.org/Test::Is)
90 | * [Test::DescribeMe](http://p3rl.org/Test::DescribeMe)
91 |
92 | These variables must be set for all phases of configuration and testing,
93 | including running Makefile.PL or Build.PL and subsequent build and test
94 | phases.
95 |
96 | CPAN smokers and integration testers must indicate automated,
97 | non-interactive testing and may request extended testing, depending on
98 | their resources.
99 |
100 | CPAN clients are free to request non-interactive or extended testing
101 | depending on their needs or configuration.
102 |
103 | CPAN smokers and clients that "must not set" a variable also must not clear
104 | it if it is already set externally.
105 |
106 | ### Amendments to the Build.PL spec
107 |
108 | David Golden and Leon Timmermans have been working on a
109 | [Build.PL](https://github.com/Perl-Toolchain-Gang/cpan-api-buildpl) spec
110 | to describe how any Perl build tool using Build.PL must behave. It is
111 | necessarily based on Module::Build, but does not need to follow its
112 | behaviors exactly.
113 |
114 | The group agreed that the use and semantics of `.modulebuildrc` should
115 | be excluded from the specification.
116 |
117 | ### Installed distributions database
118 |
119 | One of the QA hackathon projects was the creation of a replacement
120 | for packlists. An installed-distribution database would facilitate
121 | easy inventory of installed distributions, uninstall tools and tracking of
122 | the dependency graph of installed modules.
123 |
124 | The group agreed that because modules can be installed into many different
125 | locations, any such database would need to be "per @INC" and that it would
126 | need to stack in the same way that @INC itself does. That means that
127 | adding paths to @INC could change what the database sees as installed.
128 |
129 | Such a database system must not require any non-core dependencies, but
130 | could offer enhanced capabilities if recommended CPAN modules are
131 | installed.
132 |
133 | Other implementation details are left to anyone designing such a system.
134 |
135 | ### Post-installation testing
136 |
137 | Several people at the hackathon have been interested in a system for
138 | running module tests after installation, for example to ensure that
139 | upgraded dependencies don't break a module or to test overall integrity.
140 |
141 | The group agreed that any such testing must make all distribution files
142 | available during testing -- tests must be run from within a distribution
143 | tarball directory. Any such tests must be run using new `make` or
144 | `Build` targets: `make test-installed` or `Build test-installed`. These
145 | should be equivalent to `make test` or `Build test` but without adding
146 | `blib` to @INC. The `prove` application must not be used.
147 |
148 | The group also agreed that any such tests need to respect how modules can
149 | be shadowed in @INC. Setting PERL5LIB could change which is the
150 | "installed" distribution and thus which tests should run. Coordination
151 | with an installed distribution database was encouraged.
152 |
153 | Other implementation details, including whether the distribution directory
154 | is saved from the initial installation or retrieved fresh from CPAN/BackPAN,
155 | are left to anyone designing such a system.
156 |
157 | ## META file specification
158 |
159 | ### The 'provides' field
160 |
161 | The 'provides' field of the
162 | [CPAN::Meta::Spec](http://p3rl.org/CPAN::Meta::Spec) requires a 'file'
163 | sub-key, but the meaning was unclear for dynamically-generated packages.
164 | We agreed that the 'file' key must refer to the actual file within the
165 | distribution directory that originates the package, whether that is a .pm
166 | file or a .PL or other dynamic generator.
167 |
168 | ### Improving on 'conflicts'
169 |
170 | We briefly discussed some of the known problems with the 'conflicts' key
171 | within prerequisite data.
172 |
173 | What most developers seem to want is a way to indicate that installing a
174 | particular module is know to break other modules of particular versions.
175 | E.g. upgrading Foo to 2.0 breaks any Bar before 3.14.
176 |
177 | We encouraged anyone interested in improvements to prototype it using an
178 | `x_breaks` or similar custom key and getting patches to support it into
179 | CPAN clients. Once battle tested, it could be a candidate for a future v3
180 | of the spec.
181 |
182 | ## PAUSE and CPAN
183 |
184 | ### Long-term goal for distribution-level data on PAUSE
185 |
186 | Several of the PAUSE issues discussed highlighted the need for PAUSE to
187 | maintain not just package (namespace) level index and permission data, but
188 | also "distribution" level data. This would allow, for example,
189 | transferring permissions for a distribution as a unit instead of needing
190 | to transfer permissions on all packages.
191 |
192 | We agreed that this is the right long-term goal, but that other proposals
193 | would be implemented in the near-term to solve current issues.
194 |
195 | ### Case insensitive package permissions
196 |
197 | While not discussed directly, it should be noted that PAUSE package
198 | permissions will shortly become case-insensitive, but case-preserving
199 | to ensure that indexed modules would be unique even if installed on a
200 | case-insensitive file system.
201 |
202 | ### Rules for distribution naming
203 |
204 | Many CPAN ecosystem websites and tools treat a "distribution name" as
205 | a unique identifier, even though nothing has enforced uniqueness to date.
206 | Allowing non-uniqueness is confusing at best and a security risk at worst.
207 |
208 | Going forward, distributions uploaded to PAUSE must have a name that
209 | "matches" the name of an indexed package within the distribution and the
210 | uploader must have permissions for that package or else the entire
211 | distribution will not be indexed.
212 |
213 | For example, if DAGOLDEN uploads Foo-Bar-1.23.tar.gz, the distribution name
214 | is "Foo-Bar" and there must be an indexable "Foo::Bar" package within the
215 | distribution.
216 |
217 | There are about 1000 distributions on CPAN that do not follow this rule and
218 | they will be grandfathered, though they are encouraged to conform to the
219 | standard either by renaming the distribution, adding a new .pm file or by
220 | introducing a properly named package internally.
221 |
222 | For example, LWP ships as libwww-perl-6.05.tar.gz. If it included `package
223 | libwww::perl;` into one of its .pm files, that package would be indexed and
224 | would conform with the standard.
225 |
226 | Technically, the correct package could also be declared only in the
227 | META.json file using a 'provides' field. In such a case the 'file' sub-key
228 | must be 'META.json' to indicate that 'META.json' is the file responsible
229 | for declaring the package.
230 |
231 | ### Flagging abandoned modules and modules requesting help
232 |
233 | Currently, when a CPAN author passes away, his or her module permissions
234 | are transferred to a fake author called 'ADOPTME'. Volunteers can step
235 | up to request a takeover if they wish to maintain them.
236 |
237 | We agreed that in the short-term, a similar mechanism should be used to
238 | signal abandonment or that an author is looking for someone to share
239 | responsibility. Unlike the case where an author is deceased, these will
240 | use **co-maint** privileges as a signaling mechanism so that the original
241 | author may remove them as needed.
242 |
243 | (In the long-term, the group hopes that a distribution-level data model for
244 | PAUSE will be able to address these needs more directly.)
245 |
246 | CPAN search engines and other community sites may use these permissions
247 | markers and associated meanings to communicate the status of distributions.
248 |
249 | * **ADOPTME** as **primary**: this generally indicates a deceased author.
250 | Volunteers can request a takeover via modules@perl.org.
251 |
252 | * **ADOPTME** as comaint: this indicates a verified, non-responsive author.
253 | The community may propose that a package be so marked following the same
254 | rules as for a take-over (i.e. multiple attempts to contact the author
255 | and a request via modules@perl.org). Volunteers can request a takeover
256 | of an ADOPTME module via modules@perl.org without an additional waiting
257 | period.
258 |
259 | * **HANDOFF** as comaint: this indicates that an author wishes to
260 | permanently give up the primary maintainer role to someone else
261 |
262 | * **NEEDHELP** as comaint: this indicates that an author seeks people to
263 | help maintain the module, but plans to continue as primary maintainer
264 |
265 | With the exception of a 'takeover' from ADOPTME (which must go through
266 | modules@perl.org), CPAN authors must manage these comaint privileges using
267 | the regular PAUSE interface.
268 |
269 | An author may also voluntarily transfer primary or co-maint to ADOPTME to
270 | indicate that PAUSE admins may transfer permissions immediately to anyone
271 | who requests it.
272 |
273 | ### Automating PAUSE ID registration
274 |
275 | Historically, PAUSE ID's have been manually approved, often with a
276 | substantial delay. We agreed that assuming appropriate protections against
277 | bots/spam are in place, PAUSE should move to an automated approval system.
278 | This would bring it in line with other programming language repositories
279 | and open source community sites.
280 |
281 | Additionally, we agreed that unused, inactive PAUSE IDs should be deleted
282 | and made available for reuse after a period of time. Specifically, any
283 | PAUSE ID that ever uploaded anything must not be deleted (because the files
284 | exists on BackPAN under that PAUSE ID). A login to PAUSE (or via a proxy
285 | like rt.pcan.org) is sufficient to indicate activity. Inactive IDs will
286 | not be deleted without a warning message about logging in to PAUSE.
287 |
288 | ### Automating CPAN directory cleanup
289 |
290 | Approximately half the files on CPAN are older than 5 years. Many authors
291 | never clean up old distributions. In order to keep the size of CPAN down,
292 | we agreed that under certain conditions, old distribution will be
293 | automatically scheduled for deletion (and will thereafter only exist on
294 | BackPAN).
295 |
296 | For a distribution to be selected for deletion, there must be at least 3
297 | stable releases. Anything older than the oldest of those 3 will be
298 | scheduled for deletion if it is older than 5 years and is not indexed in
299 | the 02packages file.
300 |
301 | All perl tarballs will be excluded from deletion, of course.
302 |
303 | Scheduled deletion will notify the author as usual and they will have the
304 | usual period of time to cancel the scheduled deletion.
305 |
306 | Cleanup will be implemented on some sort of rolling basis by author ID to
307 | avoid bothering authors with frequent deletion notices.
308 |
309 | ### Module registration
310 |
311 | The group agreed that the PAUSE module registration has largely outlived its
312 | usefulness. Because only a fraction of CPAN modules are registered,
313 | registration does not provide a comprehensive source of metadata (e.g.
314 | "DSLIP") and much of the information registration covers is more widely
315 | available via META files.
316 |
317 | The group acknowledged the remaining benefit has been that new CPAN authors
318 | often attempt to register their first module and benefit from feedback, but
319 | felt that other venues, such as [PrePAN](http://prepan.org/), would offer a
320 | better new author experience. In particular, PrePAN offers community
321 | participation beyond one or two PAUSE admins and a wealth of examples to
322 | learn from (without having to search through a mailing list archive).
323 |
324 | Therefore, we agreed that existing PAUSE documentation will be changed to
325 | direct new (and experienced) authors to PrePAN for guidance.
326 |
327 | Soon, PAUSE will stop publishing the module registration database to CPAN
328 | mirrors. (The index file will exist but be empty to avoid breaking CPAN
329 | clients that expect it.) After an assessment period, module registration
330 | will likely be closed and this feature will be retired from PAUSE.
331 |
332 | ## Participants in the Lancaster Consensus discussions
333 |
334 | Discussions lasted over 3 days, participants came and went, but each day
335 | had about 20 people. Thank you to the following participants:
336 |
337 | Andreas König, Barbie, Breno Oliveira, Chris Williams, Christian Walde,
338 | David Golden, Daniel Perrett, Gordon Banner, H. Merijn Brand, James
339 | Mastros, Jens Rehsack, Jess Robinson, Joakim Tørmoen, Kenichi Ishigaki,
340 | Leon Timmermans, Liz Mattijsen, Matthew Horsfall, Michael Schwern, Olivier
341 | Mengué, Paul Johnson, Peter Rabbitson, Philippe Bruhat, Piers Cawley,
342 | Ricardo Signes, Salve J. Nilsen and Wendy van Dijk
343 |
344 | (Apologies to anyone present who was left off the list. Email dagolden at
345 | cpan dot org or send a pull request to be added.)
346 |
347 | ## Copyright and License
348 |
349 | This document is Copyright 2013 by David A. Golden and contributors. You
350 | can redistribute it and/or modify it under the same terms as the Perl 5
351 | programming language system itself.
352 |
--------------------------------------------------------------------------------
/lyon-amendment.md:
--------------------------------------------------------------------------------
1 | # The Lyon Amendment to the Lancaster Consensus
2 |
3 | ## Minimum-support Perl
4 |
5 | The [Lancaster Consensus](lancaster-consensus.md) wrote:
6 |
7 | > Going forward, the Perl toolchain will target Perl 5.8.1, released September
8 | > 2003. This will allow toolchain modules to reliably use PerlIO and improved
9 | > Unicode support.
10 | >
11 | > Because of the many Unicode bug-fixes in early 5.8 releases, toolchain
12 | > maintainers reserve the right to later bump the minimum to 5.8.4 (which ships
13 | > with Solaris 10).
14 |
15 | We have revised this to:
16 |
17 | No new release of a distribution in the Perl toolchain will specify a minimum
18 | perl prerequisite version (whether configure, build, runtime, or test) that has
19 | been available for less than ten years.
20 |
21 | As a special one-time exception, the minimum perl requirement on these
22 | distributions will not move past v5.16.0 until July 2024, when Red Hat
23 | Enterprise Linux and CentOS v7 leave their maintenance support phase, even
24 | though v5.16.0 was released more than 10 years ago today.
25 |
26 | The toolchain is generally understood, here, to include:
27 |
28 | * CPAN
29 | * CPAN-Meta
30 | * ExtUtils-CBuilder
31 | * ExtUtils-MakeMaker
32 | * Module-Build
33 | * Module-Metadata
34 | * Test-Harness
35 | * Test-Simple
36 | * version
37 |
38 | ...and their prerequisites.
39 |
40 |
--------------------------------------------------------------------------------
/lyon-compromise.md:
--------------------------------------------------------------------------------
1 | # The Lyon Compromise from the Perl QA Conference
2 |
3 | Adapted from to keep all the QA
4 | conference decisions together. Original gist was created by David Golden.
5 |
6 | This document summarizes broad decisions about rationalizing version object
7 | behavior based on discussions at the Lyon QAH. Participants: David Golden,
8 | Ricardo Signes, Karen Etheridge, Leon Timmermans, Peter Rabbitson and
9 | Graham Knop
10 |
11 | * version comparision should be done irrespective of the presence of
12 | underscores in the string used to initialize the version object
13 |
14 | * underscore should no longer be used as a tuple separator in vstrings or
15 | vstring-like strings; vstrings are converted to tuples by splitting into
16 | *characters* (not bytes) and converting to codepoints; any elements after
17 | the first must be in the range 0-999
18 |
19 | * numify/normal should produce a standarized string representation without
20 | underscores
21 |
22 | * stringify should produce the best possible representation of the value
23 | used to initialize the version object; it should include underscores
24 | only if the initializing value was a non-vstring string.
25 |
26 | * floating point numbers used as initializers are converted to a decimal
27 | string form at the precision limit of the architecture; people will be
28 | warned about this in the documentation
29 |
30 | Examples:
31 |
32 | Comparison:
33 | - version->new(1.0203) == version->new("1.0203")
34 | - version->new(1.02_03) == version->new("1.02_03")
35 | - version->new(v1.2.3) == version->new("v1.2.3")
36 | - version->new(v1.2.3_0) == version->new("v1.2.3_0")
37 |
38 | Underscore no longer tuple separator:
39 | - version->new(v1.2.3_0) -> tuple (1,2,30)
40 | - version->new("v1.2.3_0") -> tuple (1,2,30)
41 |
42 | Numify/normalize don't produce underscore:
43 | - version->new("1.0203")->numify -> "1.0203"
44 | - version->new("1.0203")->normal -> "v1.20.300"
45 | - version->new("1.02_03")->numify -> "1.0203"
46 | - version->new("1.02_03")->normal -> "v1.20.300"
47 | - version->new("v1.2.30")->numify -> "1.002030"
48 | - version->new("v1.2.30")->normal -> "v1.2.30"
49 | - version->new("v1.2.3_0")->numify -> "1.002030"
50 | - version->new("v1.2.3_0")->normal -> "v1.2.30"
51 |
52 | Stringify should attempt to preserve string initializers:
53 | - version->new("1.0203")->stringify -> "1.0203"
54 | - version->new("1.02_03")->stringify -> "1.02_03"
55 | - version->new("v1.2.30")->stringify -> "v1.2.30"
56 | - version->new("v1.2.3_0")->stringify -> "v1.2.3_0"
57 | - version->new(1.0203)->stringify -> "1.0203"
58 | - version->new(1.02_03)->stringify -> "1.0203"
59 | - version->new(v1.2.30)->stringify -> "v1.2.30"
60 | - version->new(v1.2.3_0)->stringify -> "v1.2.30"
61 |
--------------------------------------------------------------------------------
/oslo-consensus.md:
--------------------------------------------------------------------------------
1 | # The Oslo Consensus
2 |
3 | The Oslo Consensus was Adam Kennedy's name for an agreement reached at
4 | the 2008 Oslo QA hackathon by the attending toolchain and QA maintainers.
5 |
6 | The original was published on use.perl.org:
7 | [The Oslo Consensus](http://web.archive.org/web/20120303092604/http://use.perl.org:80/~Alias/journal/36128)
8 |
9 | ## Context and Environment Variables
10 |
11 | With regards to the concept of testing "contexts" we agreed that speculation
12 | on a complete set of testing contexts is premature at this time.
13 |
14 | However, we agreed that two particular contexts are reasonable to specify at
15 | this time, and although any formal naming system for contexts may not exist,
16 | we can identify how testing systems should know if these contexts apply with
17 | the use of environment variables.
18 |
19 | Although other shorthand methods for dealing with test contexts may be used,
20 | the environment variables will serve as the canonical flag for when they are
21 | enabled.
22 |
23 | ## AUTOMATED_TESTING
24 |
25 | We agreed that the current use of the `$ENV{AUTOMATED_TESTING}` flag to
26 | indicate an automated testing context where there is no recourse to a human
27 | operator.
28 |
29 | Although there was some discussion of a `$ENV{PERL_AUTOMATED_TESTING}`, the
30 | group overwhelmingly preferred a language-agnostic flag, particularly since
31 | the group was TAP-heavy and very much in a language-agnostic mood.
32 |
33 | We felt that keeping the context flag language-agnostic would allow for
34 | better reuse in the other environments where TAP-based testing would be done
35 | with different (or more importantly mixed) languages.
36 |
37 | Defining them as separate flags should also improve flexibility in cases
38 | where we might want to combine contexts (for example where some
39 | AUTOMATED_TESTING environments may want to also run the release tests, and
40 | others not run them). It should also make implementation simpler.
41 |
42 | ## `RELEASE_TESTING`
43 |
44 | The group felt that the use of author/release test scripts (POD testing, Perl
45 | Critic and so on) was mature and wide-spread enough that we could readonably
46 | define an environment variable for this context.
47 |
48 | Different developers and systems are currently using a variety of different
49 | flags for this context, including `$ENV{AUTHOR_TESTING}`,
50 | `$ENV{PERL_AUTHOR_TESTING}`, `$ENV{RELEASE_TESTING}` and the use of an /xt
51 | directory in the Perl distribution.
52 |
53 | The group agreed that the context was best defined as "release testing"
54 | rather than "author testing", as in by far the majority of cases the test are
55 | most-usefully run at "make dist" time, and not continuously during
56 | development.
57 |
58 | Some people reported that the use of AUTHOR_TESTING had confused some
59 | authors. Because of the use of the term "author" some authors were enabling
60 | the flag permanently, and this was not the intended use of the context.
61 |
62 | Because of this, the group agreed to standardize on `$ENV{RELEASE_TESTING}`
63 | as the canonical flag for indicating that release/author tests should be run.
64 |
65 | ## The xt/ Directory
66 |
67 | In the last few months there has been some use of a separate "xt/" directory
68 | to contain release test scripts for a distribution, and in some cases as a
69 | canonical way to describe release testing scripts.
70 |
71 | We found the concept of the xt/ directory to be reasonable, primarily because
72 | it is completely back-compatible with the legacy toolchain, and greatly
73 | simplifies the necessary code in the test scripts (because it does not need
74 | to have big chunks of `if ( $ENV{RELEASE_TESTING} ) { ... } elsif (
75 | $ENV{AUTOMATED_TESTING} ) { .. }` code in it.
76 |
77 | However, we felt that the use of a directory name as a canonical identifier
78 | was not appropriate (despite the current use of the t/ directory) because it
79 | would be difficult to manage, and combining contexts would become
80 | problematic.
81 |
82 | As a result, the group agreed that while `$ENV{RELEASE_TESTING}` would be
83 | retained as the authoritative indicator of the release-testing context, that
84 | support for using the "xt/" directory as a shorthand to contain release tests
85 | should be implemented in the toolchain modules (EU:MM, M:B, M:I, etc).
86 |
87 | This will allow for convenience in the simplest cases, and flexibility where
88 | needed.
89 |
90 | ## META.yml release_depends Key
91 |
92 | META.yml currently requires: (run-time dependencies), build_requires:
93 | (build/test/install-time dependencies) and configure_requires:
94 | (configure-time dependencies).
95 |
96 | There was some discussion about an additional release_requires: key to deal
97 | with the dependencies that the release tests requires. Although reasonable in
98 | principle, there was a feeling that this would be over-specifying, and that
99 | anyone running the release tests should be quite capable of seeing the tests
100 | fail and installing the dependencies themselves manually.
101 |
102 | In combined AUTOMATED_TESTING and RELEASE_TESTING contexts, the release tests
103 | should still be smart enough to skip_all if the modules they use are not
104 | installed.
105 |
106 | In a similar spirit, the group recommended against specifying any additional
107 | dependency contexts in META.yml, as this would be premature.
108 |
109 | As a side-note, a conversation with the FreeBSD Perl maintainers later in the
110 | day indicated that there may be some benefit in separating test_requires: out
111 | from build_requires: as FreeBSD source packages are built by users but the
112 | tests are NOT run, and as a result even once downstream packages start
113 | removing build_requires: for binary packages, this still leaves FreeBSD (and
114 | possibly Gentoo) suffering from dependency bloat in the source-build cases.
115 |
116 | However, these issues also need further investigation. As such, the group
117 | decided to recommend against additional dependency sections for META.yml at
118 | this time.
119 |
120 | ## The requires: perl Key
121 |
122 | After a quite lively discussion, it was decided that we should continue to
123 | specify the dependency for the minimum version of Perl as a "perl: $version"
124 | key within the requires: key. That is...
125 |
126 | ---
127 | requires:
128 | perl: 5.006
129 | Test::More: 0.42
130 |
131 | The group decided to retain this convention rather than have some sort of
132 | dedicated perl_version: key.
133 |
134 | The reason for this is primarily because we can get additional value from the
135 | current situation by extending the perl: key to the other dependency blocks.
136 |
137 | While I'm not particularly sure why we'd want to declare an alternative Perl
138 | version dependency for build/test context (although I'm sure someone could
139 | come up with something), we can usefully take advantage of a perl: key in
140 | configure_requires: as a superior alternative to running Makefile.PL, putting
141 | a "use 5.006" key in it, and then picking apart the resulting explosion.
142 |
143 | Because configure_requires: is authoritative, the CPAN client can check this
144 | value and be certain that the distribution is not configurable without having
145 | to execute the Makefile.PL.
146 |
147 | As such, the group agreed that the optimum but non-ideal solution is extend
148 | the perl: convention to all requires blocks.
149 |
150 | ## META_LOCAL.yml
151 |
152 | [ed. note: subsequently, this was renamed from META_LOCAL to MYMETA]
153 |
154 | An ongoing problem with the CPAN toolchain is with communication between the
155 | Makefile.PL/Build.PL scripts and the CPAN client. We currently use two
156 | entirely different communications methods and neither of them are ideal (in
157 | fact, the Makefile.PL method could be described as hackish in the extreme).
158 |
159 | An option that hasn't really been discussed in public forums (but has been
160 | bounced around between some of the toolchain developers) is the idea of using
161 | the same method we already have for communicating non-authoritative metadata
162 | (the META.yml file) to communicate the host-specific authoritative metadata.
163 |
164 | When we brought up the issue with the Oslo QA group, there was overwhelming
165 | support for the idea, and near jubilation from the Debian guys, because it
166 | would mean for the first time they can distinguish between build-time
167 | dependencies and run-time dependencies, and thus finally remove all those
168 | testing modules from the Debian binary package dependencies.
169 |
170 | After some jawboning over whether to edit the existing META.yml or write a
171 | new file (and what we might call that file) the group decided that the
172 | toolchain modules should, in addition to the existing methods, generate a
173 | file called META_LOCAL.yml.
174 |
175 | This file should contain the same metadata as META.yml, but with the various
176 | dependencies (and anything else of relevance) changed to the host-specific
177 | values.
178 |
179 | ## Summing Up
180 |
181 | With the above issues resolved, we felt that we were starting to exhaust both
182 | topics that were suitably resolvable, and more importantly the members of the
183 | group (many of whom as been stuck in TAP debates for two days).
184 |
185 | Nonetheless, we feel that the above represents a suitably thorough set of
186 | resolutions, and those with toolchain modules plan to start implementing the
187 | above immediately.
188 |
--------------------------------------------------------------------------------