X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fstrictures.pm;h=e2353f7310644732f75d0a5036a5c850714a9e0f;hb=25877bf22da1da78dc6baa2eced627ce92d78114;hp=120279946a7a6efe161f9da0e14f8d54c908cf90;hpb=d7e82ccb43d73bd4f7de8ab88aeb668fa75dda6d;p=p5sagit%2Fstrictures.git diff --git a/lib/strictures.pm b/lib/strictures.pm index 1202799..e2353f7 100644 --- a/lib/strictures.pm +++ b/lib/strictures.pm @@ -5,7 +5,7 @@ use warnings FATAL => 'all'; use constant _PERL_LT_5_8_4 => ($] < 5.008004) ? 1 : 0; -our $VERSION = '1.004000'; # 1.4.0 +our $VERSION = '1.004001'; # 1.4.1 sub VERSION { for ($_[1]) { @@ -97,9 +97,11 @@ except when called from a file which matches: (caller)[1] =~ /^(?:t|xt|lib|blib)/ -and when either '.git' or '.svn' is present in the current directory (with -the intention of only forcing extra tests on the author side) - or when the -PERL_STRICTURES_EXTRA environment variable is set, in which case +and when either C<.git> or C<.svn> is present in the current directory (with +the intention of only forcing extra tests on the author side) - or when C<.git> +or C<.svn> is present two directories up along with C (which would +indicate we are in a C operation, via L) - +or when the C environment variable is set, in which case use strictures 1; @@ -111,12 +113,12 @@ is equivalent to no multidimensional; no bareword::filehandles; -Note that _EXTRA may at some point add even more tests, with only a minor -version increase, but any changes to the effect of 'use strictures' in +Note that C may at some point add even more tests, with only a minor +version increase, but any changes to the effect of C in normal mode will involve a major version bump. If any of the extra testing modules are not present, strictures will -complain loudly, once, via warn(), and then shut up. But you really +complain loudly, once, via C, and then shut up. But you really should consider installing them, they're all great anti-footgun tools. =head1 DESCRIPTION @@ -124,7 +126,7 @@ should consider installing them, they're all great anti-footgun tools. I've been writing the equivalent of this module at the top of my code for about a year now. I figured it was time to make it shorter. -Things like the importer in 'use Moose' don't help me because they turn +Things like the importer in C don't help me because they turn warnings on but don't make them fatal - which from my point of view is useless because I want an exception to tell me my code isn't warnings clean. @@ -141,15 +143,15 @@ cost of blowing things up on another machine. Therefore, strictures turns on additional checking, but only when it thinks it's running in a test file in a VCS checkout - though if this causes undesired behaviour this can be overridden by setting the -PERL_STRICTURES_EXTRA environment variable. +C environment variable. If additional useful author side checks come to mind, I'll add them to the -_EXTRA code path only - this will result in a minor version increase (i.e. +C code path only - this will result in a minor version increase (i.e. 1.000000 to 1.001000 (1.1.0) or similar). Any fixes only to the mechanism of this code will result in a subversion increas (i.e. 1.000000 to 1.000001 (1.0.1)). -If the behaviour of 'use strictures' in normal mode changes in any way, that +If the behaviour of C in normal mode changes in any way, that will constitute a major version increase - and the code already checks when its version is tested to ensure that @@ -166,9 +168,63 @@ This method does the setup work described above in L =head2 VERSION -This method traps the strictures->VERSION(1) call produced by a use line +This method traps the C<< strictures->VERSION(1) >> call produced by a use line with a version number on it and does the version check. +=head1 EXTRA TESTING RATIONALE + +Every so often, somebody complains that they're deploying via C +and that they don't want strictures to enable itself in this case - and that +setting C to 0 isn't acceptable (additional ways to +disable extra testing would be welcome but the discussion never seems to get +that far). + +In order to allow us to skip a couple of stages and get straight to a +productive conversation, here's my current rationale for turning the +extra testing on via a heuristic: + +The extra testing is all stuff that only ever blows up at compile time; +this is intentional. So the oft raised concern that it's different code being +tested is only sort of the case - none of the modules involved affect the +final optree to my knowledge, so the author gets some additional compile +time crashes which he/she then fixes, and the rest of the testing is +completely valid for all environments. + +The point of the extra testing - especially C - is to catch +mistakes that newbie users won't even realise are mistakes without +help. For example, + + foo { ... }; + +where foo is an & prototyped sub that you forgot to import - this is +pernicious to track down since all -seems- fine until it gets called +and you get a crash. Worse still, you can fail to have imported it due +to a circular require, at which point you have a load order dependent +bug which I've seen before now -only- show up in production due to tiny +differences between the production and the development environment. I wrote +L to explain +this particular problem before L itself existed. + +As such, in my experience so far the strictures extra testing has +-avoided- production versus development differences, not caused them. + +Additionally, strictures' policy is very much "try and provide as much +protection as possible for newbies - who won't think about whether there's +an option to turn on or not" - so having only the environment variable +is not sufficient to achieve that (I get to explain that you need to add +C at least once a week on freenode #perl - newbies sometimes +completely skip steps because they don't understand that that step +is important). + +I make no claims that the heuristic is perfect - it's already been evolved +significantly over time, especially for 1.004 where we changed things to +ensure it only fires on files in your checkout (rather than strictures-using +modules you happened to have installed, which was just silly). However, I +hope the above clarifies why a heuristic approach is not only necessary but +desirable from a POV of providing new users with as much safety as possible, +and will allow any future discussion on the subject to focus on "how do we +minimise annoyance to people deploying from checkouts intentionally". + =head1 COMMUNITY AND SUPPORT =head2 IRC channel @@ -183,6 +239,10 @@ Gitweb is on http://git.shadowcat.co.uk/ and the clone URL is: git clone git://git.shadowcat.co.uk/p5sagit/strictures.git +The web interface to the repository is at: + + http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/strictures.git + =head1 AUTHOR mst - Matt S. Trout (cpan:MSTROUT)