NAME

Dist::Zilla::PluginBundle::Author::GETTY - BeLike::GETTY when you build your dists

VERSION

version 0.315

SYNOPSIS

name    = Your-App
author  = You User <you@universe.org>
license = Perl_5
copyright_holder = You User
copyright_year   = 2013

[@Author::GETTY]
author = YOUONCPAN

DESCRIPTION

This is the plugin bundle that GETTY uses. You can configure it (given values are default):

[@Author::GETTY]
author = GETTY
authority = ; optional, overrides author
deprecated = 0
release_branch = main
weaver_config = @Author::GETTY
no_cpan = 0
no_install = 0
no_makemaker = 0
no_installrelease = 0
no_changes = 0
no_podweaver = 0
include_readme = 0
xs = 0
xs_alien = ; e.g. Alien::TinyCDB for XS with Alien
installrelease_command = cpanm .

In default configuration it is equivalent to:

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

[PkgVersion]
[MetaConfig]
[MetaJSON]
[MetaProvides::Package]
inherit_version = 1
inherit_missing = 1
meta_noindex    = 1
[PodSyntaxTests]
[GithubMeta]

[InstallRelease]
install_command = cpanm .

[Authority]
:version = 1.009
authority = cpan:GETTY ; or cpan:$authority if set
do_munging = 0
do_metadata = 1

[PodWeaver]
config_plugin = @Author::GETTY

[Repository]

[Git::CheckFor::CorrectBranch]
release_branch = main

[@Git::VersionManager]
; handles versioning, changelog (NextRelease), commits, tags, and push

[GitHub::CreateRelease]
branch     = main
notes_from = ChangeLog
; notes_file defaults to "Changes" when notes_from = ChangeLog

If the task argument is given to the bundle, PodWeaver is replaced with TaskWeaver and AutoVersion is used for versioning (instead of @Git::VersionManager). You can also give a bigger major version with version:

[@Author::GETTY]
task = 1

If the manual_version argument is given, AutoVersion and Git::NextVersion are omitted.

[@Author::GETTY]
manual_version = 1.222333

You can also use shortcuts for integrating Dist::Zilla::Plugin::Run:

[@Author::GETTY]
run_after_build = script/do_this.pl --dir %s --version %s
run_before_build = script/do_this.pl --version %s
run_before_release = script/myapp_before1.pl %s
run_release = deployer.pl --dir %d --tgz %a --name %n --version %v
run_after_release = script/myapp_after.pl --archive %s --version %s
run_test = script/tester.pl --name %n --version %v some_file.ext
run_if_release_test = ./Build install
run_if_release_test = make install

You can also use add up configuration for Dist::Zilla::Plugin::Git::GatherDir, excluding root or prefix:

[@Author::GETTY]
include_readme = 1 # README.md is excluded by default
gather_include_dotfiles = 1 # activated by default
gather_include_untracked = 0
gather_exclude_filename = dir/skip
gather_exclude_match = ^local_

It also combines on request with Dist::Zilla::Plugin::Alien, you can set all parameter of the Alien plugin here, just by preceeding with alien_, the only required parameter here is alien_repo:

[@Author::GETTY]
alien_repo = http://myapp.org/releases
alien_bins = myapp myapp_helper
alien_name = myapp
alien_pattern_prefix = myapp-
alien_pattern_version = ([\d\.]+)
alien_pattern_suffix = \.tar\.gz
alien_pattern = myapp-([\d\.]+)\.tar\.gz

ATTRIBUTES

author

This is used to name the CPAN author of the distribution for the authority. See "authority" in Dist::Zilla::Plugin::Authority.

authority

Override the authority used in metadata. Use this when uploading modules originally owned by another CPAN author. For example, to upload modules with ETHER as the authority:

[@Author::GETTY]
authority = ETHER

If not set, defaults to the author value.

deprecated

Adds Dist::Zilla::Plugin::Deprecated to the distribution.

release_branch

This variable is used to set the release_branch, only releases on this branch will be allowed. See "release_branch" in Dist::Zilla::Plugin::Git::CheckFor::CorrectBranch.

weaver_config

This defines the PodWeaver config that is used. See config_plugin on Dist::Zilla::Plugin::PodWeaver.

no_github

If set to 1, this attribute will disable Dist::Zilla::Plugin::GithubMeta and will add Dist::Zilla::Plugin::Repository instead. It also disables Dist::Zilla::Plugin::GitHub::CreateRelease.

When unset, the bundle auto-detects whether the repository has a remote pointing at github.com (by scanning .git/config). If no GitHub remote is found — e.g. the dist lives on GitLab, Codeberg, a private Gitea, or has no remote at all — no_github defaults to 1 so that the GitHub-specific plugins are skipped entirely. Set no_github = 0 explicitly to force GitHub plugins on even without a detected remote.

no_github_release

If set to 1, Dist::Zilla::Plugin::GitHub::CreateRelease will not be used even though GitHub integration is otherwise active. Like "no_github", this defaults to 1 when no GitHub remote is detected in .git/config.

When this option is not set (the default), dzil release will create a GitHub Release for the new tag and attach the CPAN tarball. This requires a ~/.github-identity file in your home directory with login and token fields; the token needs write access to the repository's Contents. See Config::Identity::GitHub for authentication details (including GPG-encrypted identity files).

no_cpan

If set to 1, this attribute will disable Dist::Zilla::Plugin::UploadToCPAN. By default a dzil release would release to CPAN.

no_changes

If set to 1, then Dist::Zilla::Plugin::NextRelease (from @Git::VersionManager) will not generate changes entries.

commit_files_after_release

Extra files to fold into the release commit, forwarded to @Git::VersionManager's option of the same name (which wires them into the Git::Commit plugin's allow_dirty). Useful for companion artefacts that are rewritten by a run_before_release hook and must ship in the same commit as the version bump — e.g. a sibling Python/JS package version file.

Multi-value:

[@Author::GETTY]
run_before_release = xbin/release.pl python-prep %v
commit_files_after_release = python/locale_simple.py
commit_files_after_release = js/package.json

no_podweaver

If set to 1, then Dist::Zilla::Plugin::PodWeaver is not used.

include_readme

By default, this bundle excludes README.md from the gathered distribution files. This keeps GitHub-specific Markdown READMEs out of release tarballs and avoids awkward rendering on sites like MetaCPAN.

Set this attribute to 1 if you explicitly want to ship README.md in the distribution.

xs

If set to 1, then Dist::Zilla::Plugin::ModuleBuildTiny is used for building. This is suitable for pure-Perl XS modules that don't need external libraries. This will also automatically set no_makemaker to 1.

For XS modules that depend on Alien-provided libraries, use xs_alien instead.

no_install

If set to 1, the resulting distribution can't be installed.

no_makemaker

If set to 1, the resulting distribution will not use Dist::Zilla::Plugin::MakeMaker. This is an internal function, and you should know what you do, if you activate this flag.

no_installrelease

By default, this bundle will install your distribution after the release. If you set this attribute to 1, then this will not happen. See Dist::Zilla::Plugin::InstallRelease.

If you use the Dist::Zilla::Plugin::Alien options, then this one will not use Dist::Zilla::Plugin::InstallRelease, instead, it will use the trick mentioned in "InstallRelease" in Dist::Zilla::Plugin::Alien.

installrelease_command

If you don't like the usage of App::cpanminus to install your distribution after install, you can set another command here. See install_command on Dist::Zilla::Plugin::InstallRelease.

irc

Specify an IRC channel for support. This will be added to the distribution metadata and displayed in the SUPPORT section of the generated POD.

[@Author::GETTY]
irc = #perl

The channel name can be specified with or without the leading #.

irc_server

Specify the IRC server. Defaults to irc.perl.org.

[@Author::GETTY]
irc = #mychannel
irc_server = irc.libera.chat

irc_user

Specify the IRC username to display in the SUPPORT section. Defaults to Getty when author is GETTY.

If irc is set but irc_user is not, the IRC section will only mention the channel without referencing a specific user.

[@Author::GETTY]
irc = #perl
irc_user = Getty or ether

adoptme

If set to 1, this marks the distribution as available for adoption. This will add x_adoptme metadata to the distribution, which is recognized by MetaCPAN and displayed prominently to indicate that the current maintainer is looking for someone to take over the module.

[@Author::GETTY]
adoptme = 1

alien_build

Set to 1 for distributions that use Alien::Build to provide a C library. This automatically sets no_makemaker to 1 and adds Dist::Zilla::Plugin::AlienBuild, which generates a Makefile.PL driven by Alien::Build::MM. Ship an alienfile in the distribution root to describe how to probe for or build the library.

[@Author::GETTY]
alien_build = 1

xs_alien

For XS modules that depend on an Alien-provided library, specify the Alien module name. This automatically sets up Dist::Zilla::Plugin::MakeMaker::Awesome with the correct configuration:

[@Author::GETTY]
xs_alien = Alien::TinyCDB

The XS object name is derived from the Alien module name (e.g., Alien::TinyCDB becomes TinyCDB). If your XS file has a different name, use xs_object to override:

[@Author::GETTY]
xs_alien = Alien::TinyCDB
xs_object = MyXS

xs_object

Override the XS object name when using xs_alien. By default, the object name is derived from the Alien module name (the last component after ::).

version_finder

Restrict which files get a $VERSION rewrite. Multi-value; accepts any file finder name understood by the underlying version plugins (e.g. :MainModule, :InstallModules, :ExecFiles, or a custom FileFinder).

By default this is unset and the version plugins use their own defaults (:InstallModules and :ExecFiles). When you set it, the value is forwarded to:

Dist::Zilla::Plugin::PkgVersion (used when task or manual_version is set)
Dist::Zilla::Plugin::RewriteVersion::Transitional and Dist::Zilla::Plugin::BumpVersionAfterRelease (used via @Git::VersionManager on the default release path)

Typical use is restricting the rewrite to the main module so sibling .pm files in lib/ are not touched:

[@Author::GETTY]
version_finder = :MainModule

CONTINUOUS INTEGRATION

Every distribution using [@Author::GETTY] can share the same CI mechanics via a composite GitHub Action hosted in this bundle's repository:

Getty/p5-dist-zilla-pluginbundle-author-getty/.github/actions/dzil-test

The action installs Dist::Zilla, bootstraps all dist.ini plugins via dzil authordeps, and then installs distribution prerequisites with dzil listdeps --author. The --author flag is essential: it includes develop-phase prerequisites such as Test::Pod, which Dist::Zilla::Plugin::PodSyntaxTests (always active in this bundle) registers as a develop requires. Without it, author tests will fail with a missing module — do not paper over this by adding Test::Pod to the cpanfile's on test block.

Pure-Perl distributions

A minimal workflow for a pure-Perl dist (no system libraries required):

# .github/workflows/ci.yml
name: ci
on:
  push:
    branches: ['*']
    tags-ignore: ['*']
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        perl-version: ['5.36', '5.38', '5.40']
    container:
      image: perl:${{ matrix.perl-version }}-bookworm
    steps:
      - uses: actions/checkout@v4
      - name: Fix safe.directory
        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
      - name: perl -V
        run: perl -V
      - uses: Getty/p5-dist-zilla-pluginbundle-author-getty/.github/actions/dzil-test@main

Alien / XS distributions (system libraries)

When the distribution wraps a C library, add system-library installation before the shared action, and a second job that forces a vendored build:

jobs:
  system-lib:
    runs-on: ubuntu-latest
    container:
      image: perl:5.40-bookworm
    steps:
      - uses: actions/checkout@v4
      - name: Fix safe.directory
        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
      - run: apt-get update && apt-get install -y libfoo-dev pkg-config
      - uses: Getty/p5-dist-zilla-pluginbundle-author-getty/.github/actions/dzil-test@main

  share-build:
    runs-on: ubuntu-latest
    container:
      image: perl:5.40-bookworm
    steps:
      - uses: actions/checkout@v4
      - name: Fix safe.directory
        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
      - run: apt-get update && apt-get install -y cmake build-essential
      - uses: Getty/p5-dist-zilla-pluginbundle-author-getty/.github/actions/dzil-test@main
        with:
          install-type: share

The install-type: share input sets ALIEN_INSTALL_TYPE=share, which forces the dist to build and vendor the C library instead of using a system-provided one.

Forgejo / self-hosted Gitea

The composite action is forge-neutral (plain shell + cpanm + dzil). On a Forgejo instance, reference it with a fully-qualified URL so the action is always fetched from GitHub regardless of the instance's DEFAULT_ACTIONS_URL setting:

- uses: https://github.com/Getty/p5-dist-zilla-pluginbundle-author-getty/.github/actions/dzil-test@main

Alternatively, set DEFAULT_ACTIONS_URL = https://github.com in the Forgejo app.ini and use the short form as on GitHub.

Forgejo reads workflow files from .github/workflows/ as well as .forgejo/workflows/, so the same YAML file works on both forges.

To verify that your Forgejo instance resolves the composite action correctly, push a minimal probe workflow and watch the job log:

# .forgejo/workflows/probe.yml
name: probe
on: [push]
jobs:
  probe:
    runs-on: ubuntu-latest
    container:
      image: perl:5.40-bookworm
    steps:
      - uses: https://github.com/actions/checkout@v4
      - uses: https://github.com/Getty/p5-dist-zilla-pluginbundle-author-getty/.github/actions/dzil-test@main

If the action step fails to resolve (Forgejo does not yet support cross-repo composite actions via subdirectory paths in all configurations), the fallback is to vendor a copy of .github/actions/dzil-test/action.yml directly into each distribution repository and reference it locally:

- uses: ./.github/actions/dzil-test

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-dist-zilla-pluginbundle-author-getty/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

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

To install Dist::Zilla::PluginBundle::Author::GETTY, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Dist::Zilla::PluginBundle::Author::GETTY

CPAN shell

perl -MCPAN -e shell
install Dist::Zilla::PluginBundle::Author::GETTY

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)