Re: Possible patch to Test::Pod

Grant McLean <[email protected]> writes:

> While my patch adds a warning, in combination with Test::Pod it is
> effectively elevated to a fatal error which blocks a clean installation
> of affected distributions.

> The "correct" answer is for people who use Test::Pod to only run those
> tests on the author's system - i.e. pre release rather than pre install.
> (And ideally add the missing -=encoding too). Of course it might be a
> bit inconvenient for some maintainers to rush out a new release for that
> reason alone.

I don't think I agree with this, and I'm not sure why that would be a
recommendation.  Surely, the tests should fail if there are bugs in the
documentation?  I don't see what's different about this than any other bug
in edge functionality or minor APIs, which may not affect any particular
user but which are routinely diagnosed as bugs by the test suite.

(Full disclosure: I'm one of those people who runs Test::Pod by default in
many of my packages, both Perl modules and other packages that are
documented with POD.  I do run Pod::Spelling tests only for the
maintainer, since spell checkers and dictionaries vary too much, but I
consider Test::Pod failures to be test suite failures.)

> I'm considering a patch to make Test::Pod treat the new "missing
> =encoding" warning differently to other warnings.  The current behaviour
> is to fail the test if any warnings were generated.  Instead we could
> patch it as per the following pseudo code:

>   if no warnings
>       pass test
>   else if exactly one warning AND it's the new =encoding message
>       spit out a warning via test diag output
>       pass test
>   else
>       fail test

I think this will just make it much harder for us to clean up all the
broken POD out there.

> This would mean that an end-user having trouble with failing tests at
> install time could work around it by upgrading Test::Pod.

Why would an end-user have trouble with failing tests at install time?  If
they don't care about the failure, just ignore it and install the module
anyway.

Is there some tool involved that's refusing to install modules if the test
suite fails?  If so, I think that tool is what's buggy here, and that tool
should be fixed so that it's possible to install modules with failing
tests, since that's very common, for many reasons other than this.

-- 
Russ Allbery ([email protected])             <http://www.eyrie.org/~eagle/>