App-prepare4release
view release on metacpan or search on metacpan
[](https://github.com/neo1ite/prepare4release/blob/main/LICENSE)
[](https://www.perl.org/)
[](https://github.com/neo1ite/prepare4release/actions/workflows/ci.yml)
[](https://repology.org/project/perl%3Aapp-prepare4release/versions)
[](https://metacpan.org/pod/App/prepare4release)
[](https://cpants.cpanauthors.org/dist/App-prepare4release)
# NAME
App::prepare4release - prepare a Perl distribution for release
# SYNOPSIS
```perl
use App::prepare4release;
App::prepare4release->run(@ARGV);
```
# DESCRIPTION
Run from the distribution root (where `prepare4release.json` and `Makefile.PL`
live). The tool:
- Loads `prepare4release.json` and resolves `module_name` / `version` / `dist_name`
when omitted (from `Makefile.PL` and the main `.pm`). Invalid JSON logs a warning
and behaves like an empty object. Root keys such as `author`, `abstract`,
`license`, `min_perl_version`, `module_name`, `version_from`, and `exe_files`
are copied into `Makefile.PL` `WriteMakefile(...)` when set (see ["CONFIGURATION FILE"](#configuration-file)).
- Patches `Makefile.PL`: `META_MERGE` (`repository` and `bugtracker` URLs), and
a marked `MY::postamble` block (between `# BEGIN PREPARE4RELEASE_POSTAMBLE` and
`# END PREPARE4RELEASE_POSTAMBLE`) that runs `pod2github` when `--github` or
`--gitlab` was used (else `pod2markdown`), then `maint/inject-readme-badges.pl`
(a standalone Perl script regenerated each run, core modules only) so `make README.md`
reapplies the same shields without depending on `App::prepare4release`. The block
is refreshed on each run to match the current `pod2*` choice; the script embeds the
frozen badge Markdown for the chosen `--github` / `--gitlab` / `--cpan` flags.
- When `--github` or `--gitlab` is set, ensures CI workflow files exist (see
["Continuous integration"](#continuous-integration)).
- Regenerates `README.md` from the `VERSION_FROM` module (`make README.md` when
`Makefile` exists, otherwise `pod2github` or `pod2markdown`), then injects
Markdown shield lines (`[](link)`) into `README.md` after the first
title block (runs of `#` headings) or before `# NAME` when that is the first
heading. The `Makefile.PL` postamble runs `maint/inject-readme-badges.pl` after
`pod2github`/`pod2markdown` so badges stay in sync without a runtime dependency
on this distribution. Strips any
legacy badge block from POD after `__END__`. License and minimum Perl badges
are always added; with `--cpan`, also Repology, CPAN version, and cpants. The
GitHub Actions CI badge is added only with `--github`; the GitLab pipeline badge
only with `--gitlab` (host from `git.server`, else from `git.repo` URL, else
`gitlab.com`). License shield (always blue) uses the same key as ExtUtils::MakeMaker
(`Makefile.PL` `LICENSE`), or the type inferred from a root `LICENSE` file when
present; the link is the repository `LICENSE` blob when that file exists and
`--github` or `--gitlab` is set (branch from `git.default_branch`, default
`main`), otherwise the usual canonical license URL. Minimum Perl on the shield
comes from `min_perl_version` / `perl_min` in the JSON file, else
`Makefile.PL` `MIN_PERL_VERSION`, else the stricter of makefile and main module
(as for CI).
- Creates author tests under `xt/author/` when missing: `pod.t` ([Test::Pod](https://metacpan.org/pod/Test%3A%3APod)),
`eol.t` ([Test::EOL](https://metacpan.org/pod/Test%3A%3AEOL)), `pod-coverage.t` ([Test::Pod::Coverage](https://metacpan.org/pod/Test%3A%3APod%3A%3ACoverage)), using
[Test2::V1](https://metacpan.org/pod/Test2%3A%3AV1).
- With `--cpan`, after the steps above: ensures `LICENSE` exists. The license
_type_ is taken from `Makefile.PL` `LICENSE` (via the same snippet scan as
elsewhere in this tool); if that is missing, _perl_ (same terms as Perl 5) is
assumed. The file text is downloaded from official upstream sources (for
`perl`, the `Artistic` and `Copying` files from the Perl 5 repository; for
`apache_2`, `mit`, `gpl_3`, etc., the canonical license URLs). If a fetch
fails, a short built-in fallback is written. If `README` is missing but
`README.md` exists, writes a short stub `README` pointing readers to
`README.md`. Creates a default `MANIFEST.SKIP` when none is present (skipping
`blib/`, `cover_db/`, `nytprof/`, tarballs, `.git/`, etc.); runs
`perl Makefile.PL`, copies `MYMETA.*` to `META.*`, and `make manifest` so
`MANIFEST` matches the tree for CPAN packaging.
- Warns when any `t/*.t` or `xt/**/*.t` file starts with `use Test::More` or
`use Test::Most` (legacy assertion frameworks). Prefer [Test2::V1](https://metacpan.org/pod/Test2%3A%3AV1) or
[Test2::Tools::Spec](https://metacpan.org/pod/Test2%3A%3ATools%3A%3ASpec).
- Scans `lib/`, `bin/`, `maint/`, `t/`, and optionally `xt/` for `use` /
`require` and compares with `PREREQ_PM` / `TEST_REQUIRES` in `Makefile.PL`.
Core modules for the target minimum Perl are skipped unless a minimum module
version is given on the `use` line (see [Module::CoreList](https://metacpan.org/pod/Module%3A%3ACoreList)). By default only a
warning is printed; `--sync-deps` or `dependencies.sync` in
`prepare4release.json` updates `Makefile.PL` and appends to `cpanfile` when
present. `dependencies.skip` disables the check.
# README badge injector (`maint/inject-readme-badges.pl`)
The `MY::postamble` fragment cannot hold large, self-contained Perl _sub_s:
`ExtUtils::MakeMaker` expects that section to expand into Makefile rules, and
keeping badge logic only in `Makefile.PL` would either duplicate a lot of text
or imply loading this distribution at `make README.md` time. Instead,
`prepare4release` writes `maint/inject-readme-badges.pl`, a small, generated
program (core modules only) that strips prior shield lines and inserts the
frozen Markdown block computed on the last run (same flags as `--github` /
`--gitlab` / `--cpan`). Downstream distributions should _commit_ that file
with the rest of the tree so `make README.md` works in a clean clone and the
file is included in the CPAN tarball like any other tracked asset. Re-run
`prepare4release` after changing repository URLs, license, or badge-related
options so the script and `README.md` stay consistent. No runtime dependency on
`App::prepare4release` is added to the target module.
# CONFIGURATION FILE
File name: `prepare4release.json` (in the distribution root).
An empty file or whitespace-only file is treated as an empty JSON object `{}`.
Invalid JSON logs a warning and is treated as `{}`.
- `author`
Optional. Copied into `Makefile.PL` `AUTHOR` (distinct from `git.author`).
- `abstract`
Optional. Copied into `Makefile.PL` `ABSTRACT`.
- `abstract_from`
Optional. Copied into `Makefile.PL` `ABSTRACT_FROM`.
- `license`
( run in 0.684 second using v1.01-cache-2.11-cpan-98e64b0badf )