
CONTRIBUTING

Thank you for considering contributing to this distribution.  This file
contains instructions that will help you work with the source code.

PLEASE NOTE that if you have any questions or difficulties, you can reach the
maintainer(s) through the bug queue described later in this document
(preferred), or by emailing the releaser directly. You are not required to
follow any of the steps in this document to submit a patch or bug report;
these are just recommendations, intended to help you (and help us help you
faster).
{{
!$ENV{AUTOMATED_TESTING} && -d '.git' && `git ls-files TODO` eq "TODO\n"
  ? "\nThis distribution has a TODO file in the repository; you may want to check
there to see if your issue or patch idea is mentioned.\n"
  : ''
}}
The distribution is managed with Dist::Zilla (https://metacpan.org/release/Dist-Zilla).
{{ if ($has_xs) { <<'HAS_XS'
However, you can still compile and test the code with a small Makefile.PL
specifically for use in the repository.  You can do:

    perl Makefile.PL
    make
    make test

As well as:

  $ prove -bvr t
or
  $ perl -Mblib t/some_test_file.t
HAS_XS
} else { <<'NO_XS'
This means than many of the usual files you might expect are not in the
repository, but are generated at release time (e.g. Makefile.PL).

However, you can run tests directly using the 'prove' tool:

  $ prove -l
  $ prove -lv t/some_test_file.t
  $ prove -lvr t/

In most cases, 'prove' is entirely sufficient for you to test any patches you
have.
NO_XS
} }}
You may need to satisfy some dependencies.  The easiest way to satisfy
dependencies is to install the last release -- this is available at
https://metacpan.org/release/{{ $dist->name }}

If you use cpanminus, you can do it without downloading the tarball first:

  $ cpanm --reinstall --installdeps --with-recommends {{
  $main_package = $dist->main_module->name;
  $main_package =~ s{^lib/}{};
  $main_package =~ s{\.pm$}{};
  $main_package =~ s{/}{::}g;
  $main_package
}}

Dist::Zilla is a very powerful authoring tool, but requires a number of
author-specific plugins.  If you would like to use it for contributing,
install it from CPAN, then run one of the following commands, depending on
your CPAN client:

  $ cpan `dzil authordeps --missing`
or
  $ dzil authordeps --missing | cpanm

You should then also install any additional requirements not needed by the
dzil build but may be needed by tests or other development:

  $ cpan `dzil listdeps --author --missing`
or
  $ dzil listdeps --author --missing | cpanm

Or, you can use the 'dzil stale' command to install all requirements at once:

  $ cpan Dist::Zilla::App::Command::stale
  $ cpan `dzil stale --all`
or
  $ cpanm Dist::Zilla::App::Command::stale
  $ dzil stale --all | cpanm

You can also do this via cpanm directly:

  $ cpanm --reinstall --installdeps --with-develop --with-recommends {{ $main_package }}

Once installed, here are some dzil commands you might try:

  $ dzil build
  $ dzil test
  $ dzil test --release
  $ dzil xtest
  $ dzil listdeps --json
  $ dzil build --notgz

You can learn more about Dist::Zilla at http://dzil.org/.
{{
my $link = $dist->distmeta->{resources}{repository}{web};
if ($link and $link =~ /github/) {
"\n" . 'The code for this distribution is hosted at GitHub. The repository is:'
."\n\n".$link."\n"
.(-f '.gitmodules' ? '
This repository uses git submodules. That means you also need to run:

  $ git submodule update --init --recursive
  $ git submodule update --remote
' : '')
.'
You can submit code changes by forking the repository, pushing your code
changes to your clone, and then submitting a pull request. Please include a
suitable end-user-oriented entry in the Changes file describing your change.
Detailed instructions for doing that is available here:

https://help.github.com/articles/creating-a-pull-request'
.
(-f '.travis.yml' ?
"\n\n" . 'All pull requests for this distribution will be automatically tested on Linux
by Travis at: https://travis-ci.com/' . join('/', (split('/', $link))[-2,-1])
. "\n" . 'Results will be visible in the pull request on GitHub. Follow the appropriate
links for details when tests fail. Changes will not be mergeable until all
tests pass.'
: '')
}
}}

Generated files such as README, CONTRIBUTING, Makefile.PL, LICENSE etc should
*not* be included in your pull request, as they will be updated automatically
during the next release.

I will not accept AI-generated or AI-assisted contributions unless the nature
of the AI assistance is clearly identified with the pull request: submissions
should come from the owner's account, not a bot account, and be indistinguishable
from work done by that person. Multiple "drive-by" submissions, or contributions
that do not appear to have been human-reviewed, will be closed and may lead to
a ban of future contributions to any of my work.

If you have found a bug, but do not have an accompanying patch to fix it, you
can submit an issue report here:
{{ $dist->distmeta->{resources}{bugtracker}{web} // 'WARNING: bugtracker data not set!' }}
{{ $dist->distmeta->{resources}{bugtracker}{mailto} ? 'or via email: ' . $dist->distmeta->{resources}{bugtracker}{mailto} : '' }}
{{
my $extra = $dist->distmeta->{resources}{x_MailingList}
    ? "\n" . 'There is also a mailing list available for users of this distribution, at' . "\n" . $dist->distmeta->{resources}{x_MailingList}
    : '';
$extra .= $dist->distmeta->{resources}{x_IRC}
    ? "\n" . 'There is also an irc channel available for users of this distribution, at' . "\n" . $dist->distmeta->{resources}{x_IRC}
    : '';
# send questions to the bugtracker if nowhere better
$extra ||= 'This is a good place to send your questions about the usage of this distribution.';
}}

If you send me a patch or pull request, your name and email address will be
included in the documentation as a contributor (using the attribution on the
commit or patch), unless you specifically request for it not to be.  If you
wish to be listed under a different name or address, you should submit a pull
request to the .mailmap file to contain the correct mapping.


This file was generated via {{ ref($plugin) . ' ' . ($plugin->VERSION || '<self>') }}
from a template file originating in {{
    (my $module = $plugin->dist) =~ s/-/::/g;
    eval "require $module";
    $plugin->dist . '-' . $module->VERSION
}}.
