/ 
Dist-Zilla-PluginBundle-Author-GSG-v0.5.2
River stage zero No dependents
++
/ Dist::Zilla::PluginBundle::Author::GSG

NAME

Dist::Zilla::PluginBundle::Author::GSG - Grant Street Group CPAN dists

VERSION

version v0.5.2

SYNOPSIS

Your dist.ini can be as short as this:

    name = Foo-Bar-GSG
    [@Author::GSG]

Which is equivalent to all of this:

Some of which comes from Dist::Zilla::Plugin::Author::GSG.

    name = Foo-Bar-GSG
    author = Grant Street Group <developers@grantstreet.com>
    license = Artistic_2_0
    copyright_holder = Grant Street Group
    copyright_year = # detected from git

    [@Filter]
    -bundle = @Basic
    -remove = UploadToCPAN
    -remove = GatherDir

    ; The MakeMaker Plugin gets an additional setting
    ; in order to support "version ranges".
    eumm_version = 7.1101

    ; We try to guess which remote to use to talk to GitHub
    ; but you can hardcode a value if necessary
    github_remote = # detected from git if find_github_remote is set

    ; Enabled by default if the PluginBundle name is Author::GSG
    ; This means Filters do not automatically get it set
    find_github_remote = 1

    ; The defaults for author and license come from
    [Author::GSG]

    [ FileFinder::Filter / MungeableFiles ]
    finder => :InstallModules
    finder => :PerlExecFiles
    ; dont_munge = (?^:bin) # can be used multiple times. passed in as "skip"

    [MetaJSON]
    [OurPkgVersion]
    finder = :MungableFiles
    [Prereqs::FromCPANfile]
    [$meta_provides] # defaults to MetaProvides::Package

    [StaticInstall]
    ; mode    from static_install_mode
    ; dry_run from static_install_dry_run

    [ExecDir]
    dir = script    # in addition to bin/ for StaticInstall compatibility

    [PodWeaver]
    finder     = :MungeableFiles
    replacer = replace_with_comment
    post_code_replacer = replace_with_nothing
    config_plugin = [ @Default, Contributors ]

    [ReadmeAnyFromPod]
    [ChangelogFromGit::CPAN::Changes]
    file_name    = CHANGES
    ; Support both old 0.90 versioning and new v1.2.3 semantic versioning formats
    tag_regexp   = \b(v?\d+\.\d+(?:\.\d+)*)\b
    copy_to_root = 0

    [Git::NextVersion] # plus magic to sanitize versions from the environment
    first_version  = v0.0.1
    version_regexp = \b(v\d+\.\d+\.\d+)(?:\.\d+)*\b

    [Git::Commit]
    [Git::Tag]
    [Git::Push]

    [Git::GatherDir]
    ; include_dotfiles
    ; exclude_filename
    ; exclude_match
    exclude_filename = README.md
    exclude_filename = LICENSE.txt

    [GitHub::Meta]
    [GitHub::UploadRelease] # plus magic to work without releasing elsewhere

    [Test::Compile]
    ; test_compile_filename
    ; test_compile_phase
    ; test_compile_skip
    ; test_compile_file
    ; test_compile_fake_home
    ; test_compile_needs_display
    ; test_compile_fail_on_warning
    ; test_compile_bail_out_on_fail
    ; test_compile_module_finder
    ; test_compile_script_finder
    ; test_compile_xt_mode
    ; test_compile_switch

    [Test::ReportPrereqs]
    [Author::GSG::HasVersionTests]
    [PodSyntaxTests]
    [PodCoverageTests]

DESCRIPTION

This PluginBundle is here to make it easy for folks at GSG to release public distributions of modules as well as trying to make it easy for other folks to contribute.

The share_dir for this module includes GSG standard files to include with open source modules. Things like a standard Makefile and a contributing guide. See the "update" Makefile target for details.

The expected workflow for a module using this code is that after following the initial setup decribed below, you would manage changes via standard GitHub flow pull requests and issues. When ready for a release, you would first make update to update any included documents, commit those, and then run carton exec dzil release. You can set a specific release version with the V environment variable, as described in the Git::NextVersion Plugin documentation.

The version regexps for both the Changelog and NextVersion should be open enough to pick up the older style tags we used as well as incrementing a more strict semver.

ATTRIBUTES / PARAMETERS

github_remote / find_github_remote

Looks in the git remote list for a push remote that matches github.com (case insensitively) and if we find one, we pass it to the Git and GitHub Plugins we use.

If no remotes or multiple remotes are found, throws an exception indicating that you need to add the GitHub remote as described in "Cutting a release".

Trying to find a remote, and failing if it isn't found, is only enabled if you set find_github_remote to a truthy value. However, find_github_remote defaults to truthy if the section name for the PluginBundle is the default, @Author::GSG.

You can disable this, and fall back to each Plugin's default, by setting github_remote to an empty string.

meta_provides
    [@Author::GSG]
    meta_provides = Class

The MetaProvides subclass to use.

Defaults to Package|Dist::Zilla::Plugin::MetaProvides::Package.

If you choose something other than the default, you will need to add an "on develop" dependency to your cpanfile.

static_install_mode

Passed to Dist::Zilla::Plugin::StaticInstall as mode.

static_install_dry_run

Passed to Dist::Zilla::Plugin::StaticInstall as dry_run.

include_dotfiles

Passed to "include_dotfiles" in Dist::Zilla::Plugin::Git::GatherDir.

exclude_filename

Passed to "exclude_filename" in Dist::Zilla::Plugin::Git::GatherDir.

Automatically appends README.md and LICENSE.txt to the list.

exclude_match

Passed to "exclude_match" in Dist::Zilla::Plugin::Git::GatherDir.

test_compile_*
    [@Author::GSG]
    test_compile_skip    = ^My::NonCompiling::Module$
    test_compile_xt_mode = 1

All options for Dist::Zilla::Plugin::Test::Compile should be supported with the test_compile_ prefix.

dont_munge
    [@Author::GSG]
    dont_munge = (?^:one-off)
    dont_munge = (?^:docs/.*.txt)

Passed to Dist::Zilla::Plugin::FileFinder::Filter as c<skip> for the MungableFiles plugin.

This plugin gets passed to Dist::Zilla::Plugin::OurPkgVersion and Dist::Zilla::Plugin::PodWeaver as finder to filter matches.

Setting up a new dist

Create your dist.ini

As above, you need the name and [@Author::GSG] bundle, plus any other changes you need.

Add Dist::Zilla::PluginBundle::Author::GSG to your cpanfile

    on 'develop' => sub {
        requires 'Dist::Zilla::PluginBundle::Author::GSG';
    };

Doing this in the develop phase will cause the default Makefile not to install it, which means folks contributing to a module won't need to install all of the Dist::Zilla dependencies just to submit some patches, but will be able to run most tests.

Create a Makefile

It is recommended to keep a copy of the Makefile from this PluginBundle in your app and update it as necessary, which the target in the included Makefile will do automatically.

An initial Makefile you could use to copy one out of this PluginBundle might look like this:

    SHARE_DIR   := $(shell \
        carton exec perl -Ilib -MFile::ShareDir=dist_dir -e \
            'print eval { dist_dir("Dist-Zilla-PluginBundle-Author-GSG") } || "share"' )

    include $(SHARE_DIR)/Makefile.inc

    # Copy the SHARE_DIR Makefile over this one:
    # Making it .PHONY will force it to copy even if this one is newer.
    .PHONY: Makefile
    Makefile: $(SHARE_DIR)/Makefile.inc
        cp $< $@

Using this example Makefile does require you run carton install after adding the on 'develop' dependency to your cpanfile as described above.

If you want to override the Makefile included with this Plugin but still want to use some of the targets in it, you can rename it to something such as Makefile.inc and include it from your Makefile.

Also see the section on Makefile.PL and XS modules.

The Makefile that comes in this PluginBundle's share_dir has a many helpers to make development on a module supported by it easier.

Some of the targets that are included in the Makefile are:

test

Makes your your local cpanfile.snapshot is up-to-date and if not, will run Carton before running prove -lfr t.

testcoverage

This target runs your tests under the Devel::Cover cover utility. However, Devel::Cover is not normally a dependency, so you will need to add it to the cpanfile temporarily for this target to work.

Makefile

Copies the Makefile.inc included in this PluginBundle's share_dir into your distribution.

Actually the $(lastword $(MAKEFILE_LIST)), so if you put the Makefile somewhere else, for example Makefile.inc or ci/Makefile, that will be the target.

This should happen automatically through the magic of make.

update

Generates README.md and copies some additional files from this PluginBundle's share_dir into the repo so that the shared documents provided here will be kept up-to-date.

README.md

This is generated from the post Pod::Weaver documentation of the main module in the dist. Requires installing the develop cpanfile dependencies to work.

$(CONTRIB)

The files in this variable are copied from this PluginBundle's

Currently includes CONTRIBUTING.md.

$(CPANFILE_SNAPSHOT)

Attempts to locate the correct cpanfile.snapshot and automatically runs carton install $(CARTON_INSTALL_FLAGS) if it is out of date.

The CARTON_INSTALL_FLAGS are by default --without develop in order to avoid unnecessarily installing the heavy Dist::Zilla dependency chain.

Makefile.PL

There is special support for a Makefile.PL in the root of the repository. If using it, you will need to rename the Makefile included with this PluginBundle to something else, for example ci/Makefile or Makefile.dzil.

This is normally used for modules that need a build phase before they will pass tests, such as modules that use XS.

Generating the initial Makefile.PL can be done with:

    cp Makefile Makefile.dzil
    touch Makefile.PL dist.ini
    make Makefile.PL
    echo Makefile >> .gitignore
    git rm -f Makefile && git commit -am"Switch to Makefile.PL"

Which should copy the Makefile.PL from the dzil workspace into your repostitory.

Because this PluginBundle uses Dist::Zilla::Plugin::OurPkgVersion, actually testing XS modules is a bit troublesome because they don't have a $VERSION available. The above command will generate the Makefile.PL with an embedded version of v0.0.1 which can be used in your tests to work around this. First you need to add use vars '$VERSION'; to the .pm files that bootstrap the XS module, and then in your tests that load that module, before you use the module to be tested, you can set a default version that will match the the one in the Makefile.PL. This default will be overridden when My::Module is loaded if it has a VERSION of its own.

    BEGIN { $My::Module::VERSION = "v0.0.1" }
    use My::Module;

Cutting a release

    carton exec -- dzil release

This should calculate the new version number, build a new release tarball, add a release tag, create the release on GitHub and upload the tarball to it.

You can set the V environment variable to force a specific version, as described by Dist::Zilla::Plugin::Git::NextVersion.

    V=2.0.0 carton exec -- dzil release
Make sure your local checkout has what you want to release

Completing a dzil release will commit any changes, tag the release version to the currently checked out commit, and push to the remote.

Your git remote must be a format GitHub::UploadRelease understands

Either git@github.com:GrantsStreetGroup/$repo.git, ssh://git@github.com/GrantsStreetGroup/$repo.git, or https://github.com/GrantsStreetGroup/$repo.git.

As shown in the "Fetch URL" from git remote -n $remote,

Set github.user and github.token

You can get a GitHub token by following GitHub's instructions.

    git config --global github.user  github_login_name
    git config --global github.token token_from_instructions_above

AUTHOR

Grant Street Group <developers@grantstreet.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2019 - 2023 by Grant Street Group.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)