working-with-dist-zilla

Working with Dist::Zilla Repositories

Overview

Dist::Zilla (dzil) is a meta-tool that builds CPAN distributions from a dist.ini declaration. Many of its behaviors are stable across projects but invisible to anyone who hasn't been bitten — there's no "the docs say so" moment, you just learn by getting them wrong. This skill captures those patterns so you apply them on the first pass instead of discovering each one in an implementer/reviewer loop.

Worked example that surfaced these patterns in sequence: oalders/lwp-consolelogger#56 (Code::TidyAll → precious migration).

When to Use

Use this skill when:

• The repo contains a dist.ini file at its root
• The user mentions dzil, Dist::Zilla, @Author::* bundles, cpanfile, or META.json
• You are editing prereqs, swapping plugins, or preparing a release
• A dzil build output is producing diff noise or unexpected warnings

Don't use when:

• The repo is a plain ExtUtils::MakeMaker / Module::Build distribution with no dist.ini
• Work is unrelated to packaging (e.g. editing only lib/ source code without touching prereqs or build config)

Workflow

digraph dzil {
    "Repo orientation" [shape=box];
    "Editing prereqs?" [shape=diamond];
    "Decide PluginRemover vs RemovePrereqs" [shape=box];
    "Apply edits to dist.ini" [shape=box];
    "Run dzil build" [shape=box];
    "Decide commit vs revert" [shape=box];
    "Run dzil test --release --author" [shape=box];
    "Tests pass?" [shape=diamond];
    "Fix warnings (e.g. .mailmap)" [shape=box];
    "Commit" [shape=box];

    "Repo orientation" -> "Editing prereqs?";
    "Editing prereqs?" -> "Decide PluginRemover vs RemovePrereqs" [label="yes"];
    "Editing prereqs?" -> "Run dzil build" [label="no"];
    "Decide PluginRemover vs RemovePrereqs" -> "Apply edits to dist.ini";
    "Apply edits to dist.ini" -> "Run dzil build";
    "Run dzil build" -> "Decide commit vs revert";
    "Decide commit vs revert" -> "Run dzil test --release --author";
    "Run dzil test --release --author" -> "Tests pass?";
    "Tests pass?" -> "Fix warnings (e.g. .mailmap)" [label="warnings"];
    "Fix warnings (e.g. .mailmap)" -> "Run dzil build";
    "Tests pass?" -> "Commit" [label="clean"];
}