NAME

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

VERSION

version 0.327

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
tag_format = %v
weaver_config = @Author::GETTY
no_cpan = 0
no_install = 0
no_makemaker = 0
no_license = 0 ; 1 when no_cpan is set
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:

[Git::GatherDir]
include_dotfiles = 0
exclude_filename = README.md ; unless include_readme
exclude_filename = .karr     ; unless no_cpan

[GatherAgentContext]

[@Filter]
-bundle = @Basic
-remove = GatherDir
-remove = PruneCruft
-remove = License ; LICENSE is committed, see generate_license

[LicenseFile]     ; checks the committed LICENSE against dist.ini

[MetaConfig]
[MetaJSON]
[PodSyntaxTests]
[Test::ChangesHasContent]
[MetaProvides::Package]
inherit_version = 1
inherit_missing = 1
meta_noindex    = 1

[GithubMeta]      ; with a GitHub remote; a Gitea/Forgejo remote gets
                  ; [Author::GETTY::GiteaMeta], anything else [Repository]

[InstallRelease]
install_command = cpanm .

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

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

[Prereqs::FromCPANfile]

[PodWeaver]
config_plugin = @Author::GETTY

[@Git::VersionManager]
; handles versioning, changelog (NextRelease), commits, tags
post-release commit.allow_dirty_match = ^bin/
; ... the bundle adds this on top of the ^lib/.*\.pm$ default

[Git::Push]
push_to = origin

[GitHub::CreateRelease]   ; with a GitHub remote
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_

.karr — the tracked config file for the karr autonomous-loop prompt, not the kanban board state itself (that lives in refs/karr/*) — is also excluded from the gathered distribution files for CPAN releases (the default, no_cpan = 0). Set no_cpan = 1 to keep it in the built distribution.

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

The value may be given either bare (ETHER) or with the cpan: prefix (cpan:ETHER); both produce the same cpan:ETHER authority, so the prefix is never doubled. 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.

tag_format

Forwarded to @Git::VersionManager's Git::Tag.tag_format (or, for task/manual_version dists, to "tag_format" in Dist::Zilla::Plugin::Git::Tag directly). Defaults to %v, the bare $VERSION string (e.g. 0.317) — not a v-prefixed SemVer tag.

Override this when a release tag needs to satisfy another ecosystem's tooling, e.g. a Go module published from the same tag, which requires strict vMAJOR.MINOR.PATCH:

[@Author::GETTY]
tag_format = v%v.0

Perl's decimal $VERSION only has two parts (major.minor as one decimal number, e.g. 0.317), so the trailing .0 supplies the third, patch, part SemVer requires, yielding a tag like v0.317.0.

Note that %v is still whatever $VERSION is (Perl's own decimal versioning); this option only changes the tag's formatting, not the version scheme itself.

The matching version_regexp for Dist::Zilla::Plugin::Git::NextVersion, which finds the last release tag for a dist without $VERSION in its source, is derived from this format automatically (%v gives ^(\d[\d._]*)$, v%v.0 gives ^v(\d[\d._]*)\.0$); a format with any other % code keeps that plugin's own default ^v(.+)$.

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.

For repository metadata in the no-GitHub case the bundle is forge-aware: a remote pointing at a Gitea/Forgejo host gets proper repository/ bugtracker/homepage resources via Dist::Zilla::Plugin::Author::GETTY::GiteaMeta (the Gitea/Forgejo counterpart of Dist::Zilla::Plugin::GithubMeta); anything else falls back to the generic Dist::Zilla::Plugin::Repository. The known Gitea hosts (codeberg.org and the author's own instance) are detected automatically; for any other self-hosted Gitea/Forgejo instance set "gitea". Purely additive — GitHub-hosted distributions are unaffected.

gitea

If set to 1, the dist's git remote host is treated as a Gitea/Forgejo instance and gets repository/bugtracker/homepage META via Dist::Zilla::Plugin::Author::GETTY::GiteaMeta, built for that host. Use this for a self-hosted Gitea/Forgejo that is not one of the auto-detected known hosts. Has no effect when a GitHub remote is present (GitHub wins).

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 the repository's remotes.

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.

Dist::Zilla refuses to release without a Releaser plugin, so the bundle adds Dist::Zilla::Plugin::FakeRelease in its place, which lets dzil release run the rest of the flow (changelog, tag, version bump, push). It is left out when the dist brings a Releaser of its own: the default Docker subsection ("docker_image") or run_release. A Releaser you add by hand to your dist.ini is not seen by the bundle, so if you do that, you will have the fake one as well.

It also makes version_finder default to :MainModule.

no_changes

If set to 1, then Dist::Zilla::Plugin::NextRelease (from @Git::VersionManager) will not generate changes entries. As the version heading is then blank, Dist::Zilla::Plugin::Test::ChangesHasContent is left out as well; it is also left out for a task, which has no NextRelease either.

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

This is not needed for Perl executables: the $VERSION bump after a release covers them through the :PerlExecFiles finder, but @Git::VersionManager only allows ^lib/.*\.pm$ to be dirty in the commit that records the bump. The bundle therefore passes an additional allow_dirty_match of ^bin/ into that commit, so a bumped Perl executable is committed along with the modules instead of being left behind in the working tree.

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.

.karr is also excluded from the gathered distribution files, independently of this attribute, whenever this is a CPAN release (no_cpan = 0, the default). Set no_cpan = 1 to have it included in the built distribution.

generate_license

By default this bundle expects LICENSE to be a committed file in the repository. It removes Dist::Zilla::Plugin::License from @Basic, so the file is gathered from git like any other source file, and adds Dist::Zilla::Plugin::LicenseFile, which aborts the build when that file is missing or no longer matches the distribution's license, copyright_holder and copyright_year.

The point is the repository, not the tarball: GitHub, Gitea and Forgejo detect and link a licence from a committed LICENSE, and a generated one is never there to be found. Write the file with dzil genlicense and commit it.

Set this attribute to 1 to go back to the generated file — @Basic keeps its License plugin and no check is added. Use it for distributions that deliberately ship no committed LICENSE.

no_license

If set to 1, the bundle does nothing about LICENSE: none is generated and no committed one is demanded. A LICENSE that is committed anyway is still gathered from git like any other file, just not checked. license in dist.ini stays required by Dist::Zilla and still feeds the metadata and the POD.

This is the default with no_cpan = 1 — a distribution that never reaches CPAN is usually private and has no licence to publish. Set no_license = 0 to keep the committed-file check there, or generate_license = 1 to have the file generated. no_license = 1 together with generate_license = 1 is an error.

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 adds Dist::Zilla::Plugin::AlienBuild, which generates a Makefile.PL driven by Alien::Build::MM — no_makemaker is left at its default (0), since Alien::Build::MM munges the MakeMaker-generated Makefile.PL rather than replacing it. 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

Multi-value; forwarded verbatim as the finder option of the plugins that do the $VERSION rewrite — see those for what a finder selects:

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

By default, CPAN distributions use :InstallModules and :PerlExecFiles: modules and Perl executables get the distribution version, while Bash and other non-Perl executables are not parsed by the PPI-based version plugins. With no_cpan, the default is :MainModule. Setting the option explicitly always wins.

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.

Reference the action as ...dzil-test@v1, as in the examples below. The v1 tag is moved by the maintainer when the action changes, so a dist pinned to it gets a change only then, and not on the next CI run as with @main, where every change lands in all consuming CI runs at once.

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@v1

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@v1

  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@v1
        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@v1

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@v1

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 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.

https://raudssus.de/

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)