/ 
Dist-Zilla-PluginBundle-Prereqs-0.93
River stage one • 4 direct dependents • 5 total dependents
/ Dist::Zilla::Plugin::PrereqsClean

NAME

Dist::Zilla::Plugin::PrereqsClean - Automatically cleans up the mess from other Prereq modules

SYNOPSIS

; ...other Prereq plugins...
; (NOTE: Order is important, so PrereqsClean should go last.)
[PrereqsClean]
; defaults
minimum_perl = {{Runtime Requires for Perl}} || v5.8.8
removal_level = 2

DESCRIPTION

Ever notice that it's really easy to figure out if a module's author used Dist::Zilla by the amount of dependencies? strict? warnings? base? Every module for Foo::Bar::*, individually listed?

Well, now you can clean up that junk. PrereqsClean will find and clean up:

  • Core modules that are already in Perl, verifying minimum version requirements

  • Core modules that only exist in Perl, which will elevate the minimum Perl version if necessary

  • Multiple modules that already exist in a single distribution

Why bother?

Why even worry about the dependency list?

  1. Your list of dependencies should give users a general idea of how many distributions they need to download from CPAN. Bulking up the dependencies with every single little module scares away certain users into thinking your module is just too complex to worry about.

  2. The core module search alone will aid you in setting the most accurate minimum Perl version.

  3. It's just silly to add in stuff like strict and warnings as dependencies, when they have literally been a part of the Perl language since Day 1.

For the flip side, see "CAVEATS".

OPTIONS

minimum_perl

This is the bare minimum version of Perl you want to start off with. Some people already have a minimum in their code, which it will use by default. Otherwise, you can override here, instead of inside the modules.

The "last resort" default is v5.8.8, which is the minimum version of Perl that included EUMM.

removal_level

This dictates just how zealous this module should remove dependencies from the list. The default (level 2) should work fine for most people.

  • Level 0 = This is the completely safe and boring option. It won't actually remove anything unless the module exists only in Perl, which dependencies wouldn't have fixed anyway. It will also elevate your minimum Perl version from that discovery, and warn you of deprecated/removed modules from core Perl.

  • Level 1 = This is the "core only" removal level, which adds support to remove "dual-life" (CPAN+Perl) core modules, if the minimum version is covered in the existing version of Perl.

  • Level 2 = This is the default removal level, which will condense multiple modules into a single distribution requirement.

  • Level 3 = This level will remove the "split protection" safeguards that allow it to only remove multiple modules if they fall into the same parent namespace. (For example, split protection would remove all of the Foo::Bar::\* modules as one Foo::Bar requirement, and the Blah::\* modules as a Blah requirement, even if all of those modules are in the same distribution.)

CAVEATS

Core module deprecation

Situation: Once in a blue moon, the Perl folks will decide that a module is either too old, too broken, or too obscure to keep into core. Once that happens, there is a deprecation process. First, the module is marked as deprecated for an entire major release cycle (5.##.\*). If it was in the middle of a cycle, it will likely last another full cycle.

Finally, the module is removed from core. In many cases, the module isn't even available on CPAN, since the whole thing has been retired.

Problem: If PrereqsClean removed the module and if you haven't had a release in a large span of time (missing the entire deprecation cycle), then users might experience missing dependencies for newer versions of Perl.

Risk: As of the time of this writing, out of the 773 modules that have ever been in Perl core, 32 modules or module sets (93 indiv modules) have been removed from core, 10 of which were removed during a massive cleanup during the 5.8/9 cycle.

Given that you're using something as modern as Dist::Zilla, you're probably not depending on modules that are 10 years old. And you're probably releasing often enough that you'll run into the built-in deprecation warning before it gets removed.

Solution: If the module is still in CPAN, re-release your distro. Problem solved.

If not, you're pretty much SOL, anyway. Switch to a different module.

Distribution split

Situation: An author of a large distribution has decided that some of the modules are better off split up into another (or more) distro.

Problem: If PrereqsClean removed the module from the split, then users might experience missing dependencies. However, the chances are high that the distro author is now including the split modules in their dependency list, so CPAN will install it correctly, anyway.

Risk: This is a very rare event, but it does happen to major modules. For example, GAAS had split off all of the non-LWP modules from libwww-perl for his 6.0 release. However, again, he also included dependency links back to those modules, so CPAN would have installed it correctly. Plus, it was a logical namespace split, so PrereqsClean's "split protection" would have already safeguarded against any problems.

So, the odds of this causing any problems are very, very low.

Solution: Again, dzil release. Problem solved.

TL;DR

If any of this is too scary for you, just set the removal_level to 0.

SEE ALSO

Other Dist::Zilla Prereq plugins: Prereqs, AutoPrereqs, LatestPrereqs, DarkPAN

AVAILABILITY

The project homepage is https://github.com/SineSwiper/Dist-Zilla-PluginBundle-Prereqs.

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you, or see https://metacpan.org/module/Dist::Zilla::PluginBundle::Prereqs/.

AUTHOR

Brendan Byrd <BBYRD@CPAN.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by Brendan Byrd.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)