The Difficulties of Unwritten Community Standards

The strong sense of community standards in Perl and the CPAN offers many benefits. The uniformity of conventions suggests that all of the code I'm likely to use has decent documentation, a test suite, a project page on the CPAN, dependency tracking, and a very reasonable chance of installing correctly (or at least strong community pressure to figure out why it doesn't and to fix it).

I know that when I write about Text::AutoFormat, to choose a random module name I hadn't thought of until halfway through this sentence, I can link to search.cpan.org and you can click through to read its documentation and a synopsis of its purpose and example code will be right there. That's valuable. That's useful.

I wouldn't trade those loose standards for anything.

Even so, community standards—even ad hoc customs and conventions—are not free.

Uploading to the CPAN means understanding how to build a distribution. Some people use h2xs. Some people use Module::Starter. I've grown enamored of Dist::Zilla (and see rjbs's Managing Distributions with Dist::Zilla for good advice on how to migrate to Dzil). You get to decide whether you use ExtUtils::MakeMaker or Module::Build or Module::Install. You get to learn all about CPANTS and rt.cpan.org and META.yml.

You ask for a PAUSE account and understand what that means.

You wait nervously for a group of Perl superheroes to judge you worthy and acknowledge that that silly little idea you had is worthy to go into the mythical powerful CPAN... and it happens and you wait for other Perl gurus to critique and criticize you or other normal Perl programmers to send you patches or test failure reports or.....

All of this only happens if you go through the work of learning that you have to learn all of this and if you decide that the nervousness is worth it. (It is.) As a reward, if you keep with it, you'll discover that all of these conventions are merely conventions, that you can upload almost anything to the CPAN that isn't malicious and it'll stick around, and that the real conventions, at their inescapable core, are few.

You don't have to take a side in the CPAN toolchain argument, or even know that it exists. You don't have to stick with the standard approach to documenting your code, or writing your tests, or marking your dependencies. You don't have to follow advice about namespaces and top-level namespaces and namespace registration.

You should, but none of that is essential. (You learn that from experience, not the documentation.) It's not essential, but you still have to crawl up that learning curve to the point of minimal productivity. Good Perl programmers have automated away a lot of that complexity, but not the complexity of the initial understanding.

There's no single good default tool which lets you create a module for the CPAN without worrying about some of this complexity. Maybe it's not possible to remove all of that complexity. Maybe it shouldn't be. Yet I wonder: if it's possible to create a minimal CPAN client that almost always does the right thing without configuration, is it possible to create a tool to create distributions without configuration?

You don't have to use this tool to create distributions you upload to the CPAN, of course. Yet if the best way to manage modern Perl 5 code is with the tools of the CPAN ecosystem (and it is), we should make it easier to manage DarkPAN code in the same way. (We call it DarkPAN for a reason.)

What if we could point novices to a single utility with minimal configuration which helped them build distributions with dependency tracking, documentation, testability, installability, indexability, and everything necessary to go to the CPAN or their local CPAN mirrors? What if these defaults fit the unwritten community standards in such a way that doing the right thing is much easier than not doing it—so easy that they don't even have to read about the various standards and their evolution and controversies?

People will put up with a lot if doing the necessary thing is easy. How can we encourage that?