NAME

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

VERSION

version v0.6.1

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 <[email protected]>
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
semantic_version = 1
overwite         = 1
[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. To support this you need to add our $VERSION = 'v0.0.1'; # VERSION to the .pm files that bootstrap the XS module. This default will be overwitten by the OurPkgVersion Plugin when Dist::Zilla builds the dist.

package My::Module;

# ABSTRACT: Does things for me
our $VERSION = 'v0.0.1'; # VERSION

For XS modules, you will also need to disable static_install_mode and exclude the Makefile.PL from the dist, as the MakeMaker Plugin will want to generate one with the correct version.

[@Author::GSG]
static_install_mode = off
exclude_filename = Makefile.PL

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 [email protected]:GrantsStreetGroup/$repo.git, ssh://[email protected]/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 [email protected]

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)