Dist-Zilla-PluginBundle-Author-ETHER

A plugin bundle for distributions built by ETHER


License
Artistic-1.0-Perl

Documentation

NAME

Dist::Zilla::PluginBundle::Author::ETHER - A plugin bundle for distributions built by ETHER

VERSION

version 0.163

SYNOPSIS

In your dist.ini:

[@Author::ETHER]

DESCRIPTION

This is a Dist::Zilla plugin bundle. It is very approximately equal to the following dist.ini (following the preamble), minus some optimizations:

[Prereqs / pluginbundle version]
-phase = develop
-relationship = recommends
Dist::Zilla::PluginBundle::Author::ETHER = <current installed version>

;;; Before Build
[PromptIfStale / stale modules, build]
phase = build
module = Dist::Zilla::Plugin::Author::ETHER


;;; ExecFiles
[ExecDir]
dir = script    ; only if script dir exists


;;; Finders
[FileFinder::ByName / Examples]
dir = examples


;;; Gather Files
[Git::GatherDir]
:version = 2.016
exclude_filename = CONTRIBUTING
exclude_filename = INSTALL
exclude_filename = LICENCE
exclude_filename = LICENSE
exclude_filename = META.json
exclude_filename = Makefile.PL
exclude_filename = README.md
exclude_filename = README.pod
exclude_filename = TODO
exclude_filename = cpanfile
exclude_filename = inc/ExtUtils/MakeMaker/Dist/Zilla/Develop.pm
exclude_filename = ppport.h

[MetaYAML]
[MetaJSON]
[Readme]
[Manifest]
[License]
:version = 5.038
filename = LICENCE  ; for distributions where I have authority

[CPANFile] ; iff cpanfile = 1

[GenerateFile::FromShareDir / generate CONTRIBUTING]
-dist = Dist-Zilla-PluginBundle-Author-ETHER
-filename = CONTRIBUTING
has_xs = <dynamically-determined flag>
[InstallGuide]
:version = 1.200005

[Test::Compile]
:version = 2.039
bail_out_on_fail = 1
xt_mode = 1
script_finder = :PerlExecFiles
script_finder = Examples

[Test::NoTabs]
:version = 0.08
finder = :InstallModules
finder = :ExecFiles
finder = Examples
finder = :TestFiles
finder = :ExtraTestFiles

[Test::EOL]
:version = 0.17
finder = :InstallModules
finder = :ExecFiles
finder = Examples
finder = :TestFiles
finder = :ExtraTestFiles

[MetaTests]
[Test::CPAN::Changes]
:version = 0.012
[Test::ChangesHasContent]
[Test::MinimumVersion]
:version = 2.000010
max_target_perl = 5.006
[PodSyntaxTests]
:version = 5.040
[PodCoverageTests]
:version = 5.040
[Test::PodSpelling]
:version = 2.006003
stopwords = irc
directory = examples
directory = lib
directory = script
directory = t
directory = xt

;[Test::Pod::LinkCheck]     many outstanding bugs
[Test::Pod::No404s]
:version = 1.003
[Test::Kwalitee]
:version = 2.10
filename = xt/author/kwalitee.t
[MojibakeTests]
:version = 0.8
[Test::ReportPrereqs]
:version = 0.022
verify_prereqs = 1
version_extractor = Module::Metadata
include = Encode
include = File::Temp
include = JSON::PP
include = Module::Runtime
include = Pod::Coverage
include = Sub::Name
include = YAML
include = autodie
[Test::Portability]
:version = 2.000007
[Test::CleanNamespaces]
:version = 0.006


;;; Munge Files
[Git::Describe]
:version = 0.004
on_package_line = 1

[PodWeaver] (or [SurgicalPodWeaver])
:version = 4.008
config_plugin = @Author::ETHER ; unless weaver.ini is present
replacer = replace_with_comment
post_code_replacer = replace_with_nothing


;;; Metadata
[GithubMeta]    ; (if server = 'github' or omitted)
:version = 0.54
homepage = 0
issues = 0

[AutoMetaResources]
bugtracker.rt = 1       ; (if issues = 'rt' or omitted)
; (plus repository.* = 1 if server = 'gitmo' or 'p5sagit')

[Authority]
:version = 1.009
authority = cpan:ETHER
do_munging = 0

[MetaNoIndex]
directory = corpus
directory = demo
directory = examples
directory = fatlib
directory = inc
directory = local
directory = perl5
directory = share
directory = t
directory = xt

[MetaProvides::Package]
:version = 1.15000002
finder = :InstallModules
meta_noindex = 1
inherit_version = 0
inherit_missing = 0

[MetaConfig]
[Keywords]
:version = 0.004

; if we are releasing with a new perl with -DDEFAULT_INC_EXCLUDES_DOT set
[UseUnsafeInc]
dot_in_INC = 0

;[Git::Contributors]    ; below
;[StaticInstall]        ; below


;;; Register Prereqs
[AutoPrereqs]
:version = 5.038
[Prereqs::AuthorDeps]
phase = x_Dist_Zilla        ; (or whatever 'plugin_prereq_phase' is set to)
relation = requires         ; (or whatever 'plugin_prereq_relationship' is set to)
[MinimumPerl]
:version = 1.006
configure_finder = :NoFiles

[Prereqs / prereqs for @Author::ETHER]
-phase = x_Dist_Zilla       ; (or whatever 'plugin_prereq_phase' is set to)
-relationship = requires    ; (or whatever 'plugin_prereq_relationship' is set to)
...all the plugins this bundle uses...


;;; Install Tool
; <specified installer(s)>

[Git::Contributors]
:version = 0.029
order_by = commits

[StaticInstall]
:version = 0.005
mode = auto
dry_run = 1  ; only if authority is not ETHER


;;; Test Runner
; <specified installer(s)>
[RunExtraTests]
:version = 0.024
default_jobs = 9


;;; After Build
[CheckSelfDependency]

[Run::AfterBuild / .ackrc]
:version = 0.038
quiet = 1
run = bash -c "test -e .ackrc && grep -q -- '--ignore-dir=.latest' .ackrc || echo '--ignore-dir=.latest' >> .ackrc; if [[ `dirname '%d'` != .build ]]; then test -e .ackrc && grep -q -- '--ignore-dir=%d' .ackrc || echo '--ignore-dir=%d' >> .ackrc; fi"
[Run::AfterBuild / .latest]
:version = 0.041
quiet = 1
fatal_errors = 0
eval = if ('%d' =~ /^%n-[.[:xdigit:]]+$/) { unlink '.latest'; symlink '%d', '.latest'; }


;;; Before Release
[CheckStrictVersion]
decimal_only = 1

[CheckMetaResources]
[EnsureLatestPerl]
[PromptIfStale / stale modules, release]
phase = release
check_all_plugins = 1
check_all_prereqs = 1

[Git::Check / initial check]
allow_dirty =

[Git::CheckFor::MergeConflicts]

[Git::CheckFor::CorrectBranch]
:version = 0.004
release_branch = master

[Git::Remote::Check]
branch = master
remote_branch = master

[CheckPrereqsIndexed]
:version = 0.019
[TestRelease]
[Git::Check / after tests]
allow_dirty =
[CheckIssues]
;(ConfirmRelease)


;;; Releaser
[UploadToCPAN]


;;; After Release
[Run::AfterRelease / remove old LICENCE]    ; if switching from LICENCE -> LICENSE
:version = 0.038
quiet = 1
eval = unlink 'LICENCE'

[Run::AfterRelease / remove old LICENSE]    ; if switching from LICENSE -> LICENCE
:version = 0.038
quiet = 1
eval = unlink 'LICENSE'

[Run::AfterRelease / remove old READMEs]
:version = 0.038
quiet = 1
eval = unlink 'README.md'

[CopyFilesFromRelease / copy generated files]
filename = CONTRIBUTING
filename = INSTALL
filename = LICENCE
filename = LICENSE
filename = ppport.h
filename = cpanfile     ; iff cpanfile = 1

[ReadmeAnyFromPod]
:version = 0.142180
type = pod
location = root
phase = release

;;;;;; begin [@Git::VersionManager]

; this is actually a VersionProvider and FileMunger
[RewriteVersion::Transitional]
:version = 0.004
global = 1
fallback_version_provider = Git::NextVersion
version_regexp = ^v([\d._]+)(-TRIAL)?$

[CopyFilesFromRelease / copy Changes]
filename = Changes

[Git::Commit / release snapshot]
:version = 2.020
add_files_in = .
allow_dirty = CONTRIBUTING
allow_dirty = Changes
allow_dirty = INSTALL
allow_dirty = LICENCE
allow_dirty = LICENSE
allow_dirty = README.md
allow_dirty = README.pod
allow_dirty = cpanfile  ; iff cpanfile = 1
allow_dirty = ppport.h
commit_msg = %N-%v%t%n%n%c

[Git::Tag]
tag_message = v%v%t

[BumpVersionAfterRelease::Transitional]
:version = 0.004
global = 1
finder = :InstallModules  ; removed :ExecFiles

[NextRelease]
:version = 5.033
time_zone = UTC
format = %-8v  %{yyyy-MM-dd HH:mm:ss'Z'}d%{ (TRIAL RELEASE)}T

[Git::Commit / post-release commit]
:version = 2.020
allow_dirty = Changes
allow_dirty_match = ^lib/.*\.pm$
commit_msg = increment $VERSION after %v release

;;;;;; end [@Git::VersionManager]

[Git::Push]

[GitHub::Update]    ; (if server = 'github' or omitted)
:version = 0.40
metacpan = 1

[Run::AfterRelease / install release]
:version = 0.031
fatal_errors = 0
run = cpanm http://URMOM:mysekritpassword@pause.perl.org/pub/PAUSE/authors/id/U/UR/URMOM/%a

[Run::AfterRelease / release complete]
:version = 0.038
quiet = 1
eval = print "release complete!\xa"

; listed late, to allow all other plugins which do BeforeRelease checks to run first.
[ConfirmRelease]

; listed last, to be sure we run at the very end of each phase
; only performed if $ENV{USER} eq 'ether'
[VerifyPhases / PHASE VERIFICATION]
:version = 0.015

The distribution's code is assumed to be hosted at github; RT is used as the issue tracker (see option "rt" below). The home page in the metadata points to github, while the home page on github is updated on release to point to metacpan. The version and other metadata is derived directly from the local git repository.

OPTIONS / OVERRIDES

version

Use V=<version> in the shell to override the version of the distribution being built; otherwise the version is incremented after each release, in the *.pm files.

pod coverage

Subroutines can be considered "covered" for pod coverage tests by adding a directive to pod (as many as you'd like), as described in Pod::Coverage::TrustPod:

=for Pod::Coverage foo bar baz

spelling stopwords

Stopwords for spelling tests can be added by adding a directive to pod (as many as you'd like), as described in "ADDING STOPWORDS" in Pod::Spell:

=for stopwords foo bar baz

See also [Test::PodSpelling].

installer

Available since version 0.007.

The installer back-end(s) to use (can be specified more than once); defaults to ModuleBuildTiny::Fallback and MakeMaker::Fallback (which generates a Build.PL for normal use with no-configure-requires protection, and Makefile.PL as a fallback, containing an upgrade warning). For toolchain-grade modules, you should only use Makefile.PL-generating installers.

You can select other backends (by plugin name, without the []), with the installer option, or none if you are supplying your own, as a separate plugin(s).

Encouraged choices are:

  • installer = ModuleBuildTiny

  • installer = MakeMaker

  • installer = MakeMaker::Fallback (when used in combination with ModuleBuildTiny)

  • installer = =inc::Foo (if no configs are needed for this plugin; e.g. subclassed from [MakeMaker::Awesome])

  • installer = none (if you are providing your own elsewhere in the file, with configs)

server

Available since version 0.019.

If provided, must be one of:

  • github

    (default) metadata and release plugins are tailored to github.

  • gitmo

    metadata and release plugins are tailored to gitmo@git.moose.perl.org.

  • p5sagit

    metadata and release plugins are tailored to p5sagit@git.shadowcat.co.uk.

  • catagits

    metadata and release plugins are tailored to catagits@git.shadowcat.co.uk.

  • none

    no special configuration of metadata (relating to repositories etc) is done -- you'll need to provide this yourself.

airplane

Available since version 0.053.

A boolean option that, when set, removes the use of all plugins that use the network (generally for comparing metadata against PAUSE, and querying the remote git server), as well as blocking the use of the release command. Defaults to false; can also be set with the environment variable DZIL_AIRPLANE.

copy_file_from_release

Available in this form since version 0.076.

A file, to be present in the build, which is copied back to the source repository at release time and committed to git. Can be used more than once. Defaults to: LICENCE, LICENSE, CONTRIBUTING, Changes, ppport.h, INSTALL, as well as cpanfile if cpanfile = 1 is specified in the options; defaults are appended to, rather than overwritten.

surgical_podweaver

Available since version 0.051.

A boolean option that, when set, uses [SurgicalPodWeaver] instead of [PodWeaver], but with all the same options. Defaults to false.

changes_version_columns

Available since version 0.076.

An integer that specifies how many columns (right-padded with whitespace) are allocated in Changes entries to the version string. Defaults to 10.

licence (or license)

Available since version 0.101.

A string that specifies the name to use for the licence file. Defaults to LICENCE for distributions where I (ETHER) or any other known non-Americans have first-come permissions, or LICENSE otherwise. (The pod section for legal information is also adjusted appropriately.)

authority

Available since version 0.117.

A string of the form cpan:PAUSEID that references the PAUSE ID of the user who has primary ("first-come") authority over the distribution and main module namespace. If not provided, it is extracted from the configuration passed through to the [Authority] plugin, and finally defaults to cpan:ETHER. It is presently used for setting x_authority metadata and deciding which spelling is used for the LICENCE file (if the licence configuration is not provided).

fake_release

Available since version 0.122.

A boolean option that, when set, removes [UploadToCPAN] from the plugin list and replaces it with [FakeRelease]. Defaults to false; can also be set with the environment variable FAKE_RELEASE.

plugin_prereq_phase, plugin_prereq_relationship

If these are set, then plugins used by the bundle (with minimum version requirements) are injected into the distribution's prerequisites at the specified phase and relationship. Defaults to x_Dist_Zilla and requires. Disable with:

plugin_prereq_phase =
plugin_prereq_relationship =

Available since version 0.133.

cpanfile

Available since version 0.147.

A boolean option that, when set, adds a cpanfile to the built distribution and also commits it to the local repository after release. Beware that if the distribution has dynamic_config => 1 in metadata, this will not be a complete list of prerequisites.

bugtracker

Available since version 0.154.

When set to rt or omitted, RT is used as the bug/issue tracker. Can also be set to github, in which case GitHub issues are used as the bugtracker in distribution metadata.

other customizations

This bundle makes use of Dist::Zilla::Role::PluginBundle::PluginRemover and Dist::Zilla::Role::PluginBundle::Config::Slicer to allow further customization. (Note that even though some overridden values are inspected in this class, they are still overlaid on top of whatever this bundle eventually decides to pass - so what is in the dist.ini always trumps everything else.)

Plugins are not loaded until they are actually needed, so it is possible to --force-install this plugin bundle and -remove some plugins that do not install or are otherwise problematic.

If a weaver.ini is present in the distribution, pod is woven using it; otherwise, the behaviour is as with a weaver.ini containing the single line [@Author::ETHER] (see Pod::Weaver::PluginBundle::Author::ETHER).

NAMING SCHEME

This distribution follows best practices for author-oriented plugin bundles; for more information, see KENTNL's distribution.

SEE ALSO

SUPPORT

Bugs may be submitted through the RT bug tracker (or bug-Dist-Zilla-PluginBundle-Author-ETHER@rt.cpan.org).

There is also a mailing list available for users of this distribution, at http://dzil.org/#mailing-list.

There is also an irc channel available for users of this distribution, at #distzilla on irc.perl.org.

I am also usually active on irc, as 'ether' at irc.perl.org and irc.libera.chat.

AUTHOR

Karen Etheridge <ether@cpan.org>

CONTRIBUTORS

  • Dave Rolsky <autarch@urth.org>

  • Edward Betts <edward@4angle.com>

  • Graham Knop <haarg@haarg.org>

  • Randy Stauner <rwstauner@cpan.org>

  • Roy Ivy III <rivy@cpan.org>

  • Сергей Романов <sromanov@cpan.org>

COPYRIGHT AND LICENCE

This software is copyright (c) 2013 by Karen Etheridge.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.