[Apologies -- I hit the send button prematurely by mistake when trying to
click on something else. Continuing...]
I just got bit by an annoying problem, at least part of which highlights a
reason why I think that encouraging people to blindly add boilerplate
pod_coverage.t files is not a good practice. Or, more constructively, I'd
like to suggest that the way boilerplate pod_coverage.t file are recommended
be changed.
Description of the problem:
* A prereq module of mine uses a pod_coverage.t file, similar to what
Module::Starter::PBP recommends:
use Test::More;
eval "use Test::Pod::Coverage 1.04";
plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage"
if $@;
all_pod_coverage_ok();
* The module in question needs a Pod::Coverage of at least 0.16 given the
style of documentation it uses
* Test::Pod::Coverage has Pod::Coverage prereq of 0
Clearly the module author had a sufficiently high Pod::Coverage to pass (as
did I). However, anyone trying to install with an older version of
Pod::Coverage will fail the coverage test. The skip_all doesn't help
because it only checks that Test::Pod::Coverage exists, not that
Pod::Coverage is actually sufficient to pass the tests, and
Test::Pod::Coverage doesn't care what underlying Pod::Coverage is used.
Side nit, the docs for Test::Pod::Coverage don't even recommend checking for
the latest Test::Pod::Coverage to address its bugs:
use Test::More;
eval "use Test::Pod::Coverage 1.00";
plan skip_all => "Test::Pod::Coverage 1.00 required for testing POD coverage"
if $@;
all_pod_coverage_ok();
Leaving aside the old flame war point about whether end users ought to be
running coverage checks with all the associated dependency issues that have
nothing to do with whether the module works correctly (with my bias here
clearly evident), if we have to have boilerplate pod coverage tests, I'd
much rather see boilerplate like this, that highlights the Pod::Coverage
dependency, too:
use Test::More;
# MODULE AUTHORS: UPDATE VERSIONS BELOW TO MATCH YOUR CONFIGURATION
eval "use Pod::Coverage 0.17 ()";
plan skip_all => "Pod::Coverage 0.17 required for testing POD coverage"
if $@;
eval "use Test::Pod::Coverage 1.06";
plan skip_all => "Test::Pod::Coverage 1.06 required for testing POD
coverage" if $@;
all_pod_coverage_ok();
Thoughts? If we can get a consensus on this or a similar approach, then
perhaps we can get it consistently used across Module::Starter and friends,
ExtUtils::ModuleMaker and friends, and CPANTS documentation.
Sincerely,
David Golden
