This is an automated email from the git hooks/post-receive script.

abe pushed a commit to annotated tag 0.2.0-source
in repository libdist-zilla-role-bootstrap-perl.

commit 322740b88dffaa04695d45a4a55437f3f2aa494a
Author: Kent Fredric <kentfred...@gmail.com>
Date:   Sat Sep 21 21:25:20 2013 +1200

    Document and make xtests happy
---
 README.mkdn                      | 75 +++++++++++++++++++++++++++++++
 dist.ini                         |  2 +-
 lib/Dist/Zilla/Role/Bootstrap.pm | 97 +++++++++++++++++++++++++++++++++++++++-
 perlcritic.rc                    |  4 +-
 weaver.ini                       | 16 ++-----
 5 files changed, 177 insertions(+), 17 deletions(-)

diff --git a/README.mkdn b/README.mkdn
index fe78c3a..99eaeb6 100644
--- a/README.mkdn
+++ b/README.mkdn
@@ -32,34 +32,109 @@ For users of plugins:
 
 ## `bootstrap`
 
+Any user specified `bootstrap` method will be invoked during 
`plugin_from_config`.
+
+This is __AFTER__ `->new`, __AFTER__ `->BUILD`, and __AFTER__ `dzil`'s 
internal `plugin_from_config` steps.
+
+This occurs within the `register_component` phase of the plug-in loading and 
configuration.
+
+This also occurs __BEFORE__ `Dist::Zilla` attaches the plug-in into the 
plug-in stash.
+
 # ATTRIBUTES
 
 ## `distname`
 
+The name of the distribution.
+
+This value is vivified by asking `zilla->name`.
+
+Usually this value is populated by `dist.ini` in the property `name`
+
+However, occasionally, this value is discovered by a `plugin`.
+
+In such a case, that plugin cannot be bootstrapped, because that plugin 
__MUST__ be loaded prior to bootstrap.
+
 ## `try_built`
 
+This attribute controls how the consuming `plugin` behaves.
+
+- false __(default)__ : bootstrapping is only done to `PROJECTROOT/lib`
+- true : bootstrap attempts to try `PROJECTROOT/<distname>-<version>/lib`
+
 ## `fallback`
 
+This attribute is for use in conjunction with `try_built`
+
+- `false` : When `PROJECTROOT/<distname>-<version>` does not exist, don't 
perform any bootstrapping
+- `true` __(default)__ : When `PROJECTROOT/<distname>-<version>` does not 
exist, bootstrap to `PROJECTROOT/lib`
+
 ## `try_built_method`
 
+This attribute controls how `try_built` behaves when multiple directories 
exist that match `PROJECTROOT/<distname>-.*`
+
+Two valid options at this time:
+
+- `mtime` __(default)__ : Pick the directory with the most recent `mtime`
+- `parseversion` : Attempt to parse versions on all candidate directories and 
use the one with the largest version.
+
+Prior to `0.2.0` this property did not exist, and default behaviour was to 
assume `0 Candidates` and `2 or more Candidates` were the same problem.
+
 # PRIVATE ATTRIBUTES
 
 ## `_cwd`
 
 ## `_bootstrap_root`
 
+Internal: This is the real legwork, and resolves the base directory using the 
bootstrap resolution protocol.
+
+It should always return a project root of some kind, whether it be a source 
tree, or built source tree.
+
+It can also return `undef` if discovery concludes that no bootstrap can or 
should be performed.
+
 # PRIVATE METHODS
 
 ## `_pick_latest_mtime`
 
+"Latest" `mtime` candidate selector
+
+    my $directory = $self->_pick_latest_mtime(@directory_objects)
+
 ## `_get_candidate_version`
 
+Attempt to resolve a version from a directory name
+
+    my $version = $self->_get_candidate_version($directory_object)
+
+__NOTE:__ At this time, the presence of `-TRIAL` is simply stripped and ignored
+
 ## `_pick_latest_parseversion`
 
+"Latest" `version` candidate selector
+
+    my $directory = $self->_pick_latest_parseversion(@directory_objects)
+
 ## `_pick_candidate`
 
+Pick a directory from a list of candidates using the method described by 
`try_built_method`
+
+    my $directory = $self->_pick_candidate( @directory_objects );
+
 ## `_add_inc`
 
+Internal: Used to perform the final step of injecting library paths into `@INC`
+
+    $self->_add_inc("$libraryPath");
+
+# PRIVATE FUNCTIONS
+
+## `_max_by`
+
+Proxy for 
[`List::UtilsBy::__max\_by__`](http://search.cpan.org/perldoc?List::UtilsBy#max\_by)
+
+## `_nmax_by`
+
+Proxy for 
[`List::UtilsBy::__nmax\_by__`](http://search.cpan.org/perldoc?List::UtilsBy#nmax\_by)
+
 {
     "namespace":"Dist::Zilla::Role::Bootstrap",
     "interface":"role",
diff --git a/dist.ini b/dist.ini
index 90b9bb6..12df089 100644
--- a/dist.ini
+++ b/dist.ini
@@ -4,7 +4,7 @@ author           = Kent Fredric <kentfred...@gmail.com>
 license          = Perl_5
 copyright_holder = Kent Fredric <kentfred...@gmail.com>
 
-; Uncomment this to bootstrap via self 
+; Uncomment this to bootstrap via self
 ; [Bootstrap::lib]
 ; try_built = 1
 
diff --git a/lib/Dist/Zilla/Role/Bootstrap.pm b/lib/Dist/Zilla/Role/Bootstrap.pm
index a40eccc..9df9194 100644
--- a/lib/Dist/Zilla/Role/Bootstrap.pm
+++ b/lib/Dist/Zilla/Role/Bootstrap.pm
@@ -41,12 +41,18 @@ For users of plugins:
 
     fallback  = 0 ; # don't bootstrap at all if /Dist-Name-.*/ matches != 1 
things
     fallback  = 1 ; # fallback to / if /Dist-Name-.*/ matches != 1 things
-   
+
 
 =cut
 
 with 'Dist::Zilla::Role::Plugin';
 
+=p_func C<_max_by>
+
+Proxy for L<< C<List::UtilsBy::B<max_by>>|List::UtilsBy/max_by >>
+
+=cut
+
 sub _max_by(&@) {
   no warnings 'redefine';
   require List::UtilsBy;
@@ -54,6 +60,12 @@ sub _max_by(&@) {
   goto &List::UtilsBy::max_by;
 }
 
+=p_func C<_nmax_by>
+
+Proxy for L<< C<List::UtilsBy::B<nmax_by>>|List::UtilsBy/nmax_by >>
+
+=cut
+
 sub _nmax_by(&@) {
   no warnings 'redefine';
   require List::UtilsBy;
@@ -80,6 +92,16 @@ around 'dump_config' => sub {
 
 =attr C<distname>
 
+The name of the distribution.
+
+This value is vivified by asking C<< zilla->name >>.
+
+Usually this value is populated by C<dist.ini> in the property C<name>
+
+However, occasionally, this value is discovered by a C<plugin>.
+
+In such a case, that plugin cannot be bootstrapped, because that plugin 
B<MUST> be loaded prior to bootstrap.
+
 =cut
 
 has distname => ( isa => 'Str', is => ro =>, lazy => 1, builder => sub { 
$_[0]->zilla->name; }, );
@@ -100,6 +122,17 @@ has _cwd => (
 
 =attr C<try_built>
 
+This attribute controls how the consuming C<plugin> behaves.
+
+=over 4
+
+=item * false B<(default)> : bootstrapping is only done to C<PROJECTROOT/lib>
+
+=item * true : bootstrap attempts to try C<< 
PROJECTROOT/<distname>-<version>/lib >>
+
+=back
+
+
 =cut
 
 has try_built => (
@@ -111,6 +144,16 @@ has try_built => (
 
 =attr C<fallback>
 
+This attribute is for use in conjunction with C<try_built>
+
+=over 4
+
+=item * C<false> : When C<< PROJECTROOT/<distname>-<version> >> does not 
exist, don't perform any bootstrapping
+
+=item * C<true> B<(default)> : When C<< PROJECTROOT/<distname>-<version> >> 
does not exist, bootstrap to C<< PROJECTROOT/lib >>
+
+=back
+
 =cut
 
 has fallback => (
@@ -122,17 +165,35 @@ has fallback => (
 
 =attr C<try_built_method>
 
+This attribute controls how C<try_built> behaves when multiple directories 
exist that match C<< PROJECTROOT/<distname>-.* >>
+
+Two valid options at this time:
+
+=over 4
+
+=item * C<mtime> B<(default)> : Pick the directory with the most recent 
C<mtime>
+
+=item * C<parseversion> : Attempt to parse versions on all candidate 
directories and use the one with the largest version.
+
+=back
+
+Prior to C<0.2.0> this property did not exist, and default behaviour was to 
assume C<0 Candidates> and C<2 or more Candidates> were the same problem.
+
 =cut
 
 has try_built_method => (
   isa     => 'Str',
   is      => ro =>,
   lazy    => 1,
-  builder => sub { return 'mtime' }
+  builder => sub { return 'mtime' },
 );
 
 =p_method C<_pick_latest_mtime>
 
+"Latest" C<mtime> candidate selector
+
+    my $directory = $self->_pick_latest_mtime(@directory_objects)
+
 =cut
 
 sub _pick_latest_mtime {
@@ -142,6 +203,12 @@ sub _pick_latest_mtime {
 
 =p_method C<_get_candidate_version>
 
+Attempt to resolve a version from a directory name
+
+    my $version = $self->_get_candidate_version($directory_object)
+
+B<NOTE:> At this time, the presence of C<-TRIAL> is simply stripped and ignored
+
 =cut
 
 sub _get_candidate_version {
@@ -157,6 +224,10 @@ sub _get_candidate_version {
 
 =p_method C<_pick_latest_parseversion>
 
+"Latest" C<version> candidate selector
+
+    my $directory = $self->_pick_latest_parseversion(@directory_objects)
+
 =cut
 
 sub _pick_latest_parseversion {
@@ -171,6 +242,10 @@ my (%methods) = (
 
 =p_method C<_pick_candidate>
 
+Pick a directory from a list of candidates using the method described by 
C<try_built_method>
+
+    my $directory = $self->_pick_candidate( @directory_objects );
+
 =cut
 
 sub _pick_candidate {
@@ -186,6 +261,12 @@ sub _pick_candidate {
 
 =p_attr C<_bootstrap_root>
 
+Internal: This is the real legwork, and resolves the base directory using the 
bootstrap resolution protocol.
+
+It should always return a project root of some kind, whether it be a source 
tree, or built source tree.
+
+It can also return C<undef> if discovery concludes that no bootstrap can or 
should be performed.
+
 =cut
 
 has _bootstrap_root => (
@@ -222,6 +303,10 @@ has _bootstrap_root => (
 
 =p_method C<_add_inc>
 
+Internal: Used to perform the final step of injecting library paths into 
C<@INC>
+
+    $self->_add_inc("$libraryPath");
+
 =cut
 
 sub _add_inc {
@@ -236,6 +321,14 @@ sub _add_inc {
 
 =requires C<bootstrap>
 
+Any user specified C<bootstrap> method will be invoked during 
C<plugin_from_config>.
+
+This is B<AFTER> C<< ->new >>, B<AFTER> C<< ->BUILD >>, and B<AFTER> C<dzil>'s 
internal C<plugin_from_config> steps.
+
+This occurs within the C<register_component> phase of the plug-in loading and 
configuration.
+
+This also occurs B<BEFORE> C<Dist::Zilla> attaches the plug-in into the 
plug-in stash.
+
 =cut
 
 requires 'bootstrap';
diff --git a/perlcritic.rc b/perlcritic.rc
index 8c0d884..a59e977 100644
--- a/perlcritic.rc
+++ b/perlcritic.rc
@@ -1,5 +1,5 @@
 severity = 1
-exclude = RequireTidyCode RequirePodSections ProhibitPostfixControls 
RequireRcsKeywords RequireExplicitPackage
+exclude = RequireTidyCode RequirePodSections ProhibitPostfixControls 
RequireRcsKeywords RequireExplicitPackage ProhibitNoWarnings 
ProhibitSubroutinePrototypes
 include = Moose::ProhibitMultipleWiths Moose::ProhibitNewMethod 
Moose::RequireCleanNamespace Moose::RequireMakeImmutable
 color = 1
 verbose = 9
@@ -10,7 +10,7 @@ allow_includes = 1
 [CodeLayout::ProhibitTrailingWhitespace]
 
 [Documentation::PodSpelling]
-stop_words =
+stop_words = behaviour
 
 [Subroutines::ProhibitUnusedPrivateSubroutines]
 private_name_regex = _(?!build_)\w
diff --git a/weaver.ini b/weaver.ini
index 735607b..55ce96e 100644
--- a/weaver.ini
+++ b/weaver.ini
@@ -24,18 +24,6 @@ command = method
 [Collect / ATTRIBUTES]
 command = attr
 
-;[Collect / FILTER_METHODS]
-;header = FILTER METHODS
-;command = filter
-
-;[Collect / TERMINATOR_LIST_METHODS]
-;header = TERMINATOR LIST METHODS
-;command = terminator
-
-;[Collect / MIRROR_LIST_METHODS]
-;header  = MIRROR LIST METHODS
-;command = mirrorlist
-
 [Collect / PRIVATE_ATTRIBUTES]
 header  = PRIVATE ATTRIBUTES
 command = p_attr
@@ -44,6 +32,10 @@ command = p_attr
 header = PRIVATE METHODS
 command = p_method
 
+[Collect / PRIVATE_FUNCTIONS]
+header = PRIVATE FUNCTIONS
+command = p_func
+
 [Leftovers]
 
 [Region  / postlude]

-- 
Alioth's /usr/local/bin/git-commit-notice on 
/srv/git.debian.org/git/pkg-perl/packages/libdist-zilla-role-bootstrap-perl.git

_______________________________________________
Pkg-perl-cvs-commits mailing list
Pkg-perl-cvs-commits@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-perl-cvs-commits

Reply via email to