NAME

Dist::AutomationPolicy - generate and parse distribution automation policies

VERSION

version v0.2.2

SYNOPSIS

To create an automation policy file:

use Dist::AutomationPolicy;
use Path::Tiny qw( path ) 0.130;

my $pol = Dist::AutomationPolicy->new(
    distribution            => "Dist-AutomationPolicy-v0.1.0",
    code_generation         => "toolchain",
    automated_contributions => "issue",
    automated_actions       => "code_request",
    models                  => [ "claude-sonnet-4.6" ],
);

if ( $pol->validate ) {
    my $path = path( ".", $pol->filename ); # "CPAN-META/automation-policy.json"
    $path->parent->mkdir;
    $path->spew_raw( $pol->to_json );
}

To read an automation policy file:

my $path = path( "CPAN-META/automation-policy.json" );

my $pol  = Dist::AutomationPolicy->from_json( json => $path->slurp_raw );

DESCRIPTION

This module allows package maintainers to specify machine-readable metadata about their policies regarding automation: how code is generated, whether automated contributions are allowed, and whether there are automated actions run by the maintainers.

This is separate but complimentary to including an AI_POLICY.md or CONTRIBUTING.md file in the distribution.

ATTRIBUTES

version

$pol->version(1);

This is the automation policy version. It defaults to 1, and that is the only version of the specification supported.

distribution

$pol->distribution( "Dist-AutomationPolicy-v0.1.0" );

This is an optional name for the distribution that this applies to.

It accepts a distribution name with an optional version.

has_distribution

The predicate for "distribution".

description

This is an optional description.

has_description

The predicate for "description".

document

This is the name of a text document explaining this policy, e.g. AI_POLICY.md.

The path is relative to the distribution root.

has_document

The predicate for "document".

code_generation

This outlines how automated tools will generate or update the code and documentation.

It accepts the following values:

toolchain

This means that any code changes are made by the standard tools only, e.g. generation of META.json, README, updates to the POD or incrementing the version as part of the build and release process.

This implicitly includes dynamic code made by frameworks such as Moose, DBIx::Class or by curried methods.

This implicitly includes preprocessors, e.g. CSS or JavaScript tools like SASS, TypeScript, or various minifiers.

No external databases are used to generate any code, nor are any included in the code.

No generative AI is used in this process.

external_sources

Code is generated or updated from external sources, e.g. the Olson timezone database, or data from schema.org.

This includes simply copying data files to be used via something like File::ShareDir by an otherwise unchanged module.

This includes templates from external sources.

Data and templates that have been manually modified are still considered to be from external sources.

machine_generated

Some of the code has been generated by AI agents.

Code that has been manually modified is still considered to be from external sources.

Where possible, models should be documented in "models".

Note: there is no "none" option because modern Perl distributions are not written entirely by hand. There are some files in the distribution that are generated by tools.

automated_contributions

This refers to automated contributions from entities that are not controlled by or explicitly granted access by the maintainers, e.g. a bot run by a third party identifies a bug and submits a report to the distribution.

It is assumed machine-generated contributions that are manually approved, edited or submitted by a person are "automated", but it is up to project maintainers to decide whether this is an acceptable.

Note that it is up to the maintainers to decide on rate limits to contributions, and how exceeding permissions or rate limits will be handled.

none

Machine-generated contributions will not be accepted.

comment

Agents are allowed to post comments on existing issues or pull requests.

These may not require human moderation.

issue

Agents may create issues or submit security vulnerability reports.

These may not require human moderation.

code_request

Agents may submit patches or pull requests without human intervention.

These may not require human moderation.

When known, models should be documented in "models".

Note that for contributions it is assumed that "code_change" and "release" are not relevant.

automated_actions

This refers to automated changes on code or documentation made by agents that are controlled or explicitly granted access by the project maintainers.

none

There is no automation beyond changes made as part of the "toolchain" for "code_generation".

There are no scripted actions in the code repository, e.g. GitHub actions.

comment

There are scripted actions which may run tests, analyse or comment on issues or code changes (pull requests).

These may not require human moderation.

issue

Automated tools can create, modify or close issues.

These may not require human moderation.

code_request

Automated tools can create or update pull requests, but not merge then on their own.

These may not require human moderation.

Where possible, models should be documented in "models".

code_change

Automated tools can merge patches or pull requests.

These may not require human moderation.

Where possible, models should be documented in "models".

release

Automated tools can create and upload releases without human intervention.

Where possible, models should be documented in "models".

models

This is an optional array reference of Model IDs used for "automated_actions", and (when known) "automated_contributions".

Model IDs should come from https://docs.aimlapi.com/api-references/model-database, but it is not a requirement.

This was added in v0.2.0.

filename

This is the file path (relative to the project root) that the policy will be saved in.

template

This is a constructor-only attribute that is used to specify common use-case templates.

no_automation

No code is generated beyond the toolchain.

No automated contributions are accepted.

No automated actions beyond basic scripting that might comment on issues or pull requests.

issues_only

No code is generated beyond the toolchain.

Automated contributions or actions may submit comments and issues.

human_supervised

Code may be generated by AI or LLMs, and patches or pull requests may be submitted by contributors or agents run by the maintainers.

However, all code changes and releases must be reviewed and approved by the maintainers.

data_driven_updates

A use case for this is a cron job that checks for an updated external database, adapts the data into a new version of a module, and uploads a new release to CPAN.

Code is updated from external sources, and released automatically.

Automated contributions may post comments or issues.

full_automation

Code is generated by AI or LLMs, automated contributions can submit patches or pull requests, and agents operated by the maintainers can make changes to the code and release automatically.

This is discouraged.

METHODS

data

my %data = $pol->data->%*;

This returns a hash reference of the data used to generate the policy file.

validate

if ( $pol->validate( \%data ) ) ...

The validates the data according to the schema.

If no \%data is passed to it, then it validates the "data".

to_json

my $json = $pol->to_json;

This returns the JSON form of the "data".

from_json

my $pol = Dist::AutomationPolicy->from_json( $json );

my $pol = Dist::AutomationPolicy->from_json( \%data );

This is an alternative constructor that accepts a JSON string or hash reference of "data".

SOURCE

The development version is on github at https://github.com/robrwo/perl-Dist-AutomationPolicy and may be cloned from https://github.com/robrwo/perl-Dist-AutomationPolicy.git

SUPPORT

Only the latest version of this module will be supported.

This module requires Perl v5.24 or later. Future releases may only support Perl versions released in the last ten (10) years.

Reporting Bugs and Submitting Feature Requests

Please report any bugs or feature requests on the bugtracker website https://github.com/robrwo/perl-Dist-AutomationPolicy/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

If the bug you are reporting has security implications which make it inappropriate to send to a public issue tracker, then see SECURITY.md for instructions how to report security vulnerabilities.

AUTHOR

Robert Rothenberg <perl@rhizomnic.com>

The ideas for this policy emerged from discussions at the 2026 Perl Toolchain Summit.

Thanks to Leon Timmermans, Nicolas Rochelemagne, Salve J. Nilsen, Thibault Duponchelle, Timothy Legge Todd Rinaldo, and others for suggestions and feedback.

CONTRIBUTOR

Leon Timmermans <fawaka@gmail.com>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

To install Dist::AutomationPolicy, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Dist::AutomationPolicy

CPAN shell

perl -MCPAN -e shell
install Dist::AutomationPolicy

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)

NAME

VERSION

SYNOPSIS

DESCRIPTION

ATTRIBUTES

version

distribution

has_distribution

description

has_description

document

has_document

code_generation

automated_contributions

automated_actions

models

filename

template

METHODS

data

validate

to_json

from_json

SEE ALSO

SOURCE

SUPPORT

Reporting Bugs and Submitting Feature Requests

AUTHOR

CONTRIBUTOR

COPYRIGHT AND LICENSE

Module Install Instructions

Keyboard Shortcuts