NAME
Dist::Zilla::Plugin::Software::Policies - Create project policy files
VERSION
version 0.001
SYNOPSIS
DESCRIPTION
STATUS
Dist-Zilla-Plugin-Software-Policies is currently being developed so changes in the API are possible, though not likely.
[Software::Policies / Contributing]
class = PerlDistZilla
[Software::Policies / CodeOfConduct]
class = ContributorCovenant
version = 2.1
[Test::Software::Policies]
include_policy = Contributing
include_policy = CodeOfConduct
include_policy = License
include_policy = SecurityDist-Zilla-Plugin-Software-Policies is a Dist::Zilla command, plugin and test plugin for creating different policy and related files which are commonly present in repositories. Many of these are practically boilerplate but it is good to have them present in the repository, especially if the repository is public.
Examples are CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, FUNDING.md, SUPPORT.md and LICENSE.
The trouble with boilerplate files is that they are easy to forget. You either forget to place them in the repository in the first place, or you forget to update them when distribution changes.
One way to handle that problem is to create the files during the build and only include them in the distribution archive. But that means they would not be present in the repository itself which is more important nowadays because the repo is public. In GitHub, GitLab and similar hosting services, the repository becomes the public frontend of the project, not just a place of work and a heap of source code from which a release is created.
Some public hosting sites, such as GitHub, place extra weight on these files, and having them is seen as an indicator of project health and of being welcoming community engagement. GitHub allows searching for projects with different parameters and it provides a special interface for files which contain license, code of conduct, contribution guidelines and support contact information. To increase the visibility of the project, and make it easier for others to find it, it is important to have these files present - even when they provide little benefit for the actual users or developers of the repository.
With this package, creating and maintaining the files is quick and easy.
USAGE
To use Dist-Zilla-Plugin-Software-Policies, first add a test to your dist.ini file to ensure the wanted files are present and up-to-date when you run dzil test or dzil release.
[Test::Software::Policies]
include_policy = Contributing
include_policy = CodeOfConduct
include_policy = License
include_policy = SecurityUse include_policy configuration item as many times as you need to specify the wanted policy files, or leave it out completely to test for all available (installed) policies.
The package Software::Policies is a framework which is easy to expand to accommodate for future policy files.
The policy files are created from the distribution metadata present in dist.ini file. If you need to change the default values for things like distribution name, contact information or supported Perl versions, you need to set individual configuration for that policy:
[Software::Policies / Contributing]
class = PerlDistZilla
[Software::Policies / CodeOfConduct]
class = ContributorCovenant
version = 2.1
[Software::Policies / License]
use_double_license_for_perl5 = false
format = text
[Software::Policies / Security]
policy_attribute = maintainer=Policies Team <policies.team@example.com
policy_attribute = report_url=https://github.com/mikkoi/software-policies/security/advisoriesThe plugin Dist::Zilla::Plugin::Software::Policies does not actually do anything, except verify the configuration is correct. The configuration is used by Dist::Zilla::Plugin::Test::Software::Policies when creating the test files during the build phase. By default the tests are placed in xt/author directory, e.g. xt/author/policy_Contributing.t
The configuration is also used by the command dzil policies. Run the command when you need to create or update the policy files, for example, if the tests have failed.
# usage: dzil policies [<policy>] [--class] [--class-version] [--format]
dzil policies Contributing
# or, to create all policies
dzil policiesDuring the build phase, when Dist::Zilla::Plugin::Test::Software::Policies prepares the test files, it runs the policy generation in Software::Policies and embeds the result into the equivalent test file. During test phase this is compared with the existing file.
ATTRIBUTES
class
Same policy can take many forms. These are called classes.
version
Internal version of the class.
format
The format of the document when it is generated. Mostly markdown but in some cases, for example licenses, is text.
policy_attribute
Attributes that are policy or class specific.
dir
The directory name for the resulting file(s). Default: project root.
Usually policy files are at the root of the repository but lately GitHub has allowed other location where they are detected automatically, .github and docs directories.
Please see Creating a default community health file.
filename
The file name of the resulting file. This is only useful when the policy is written as only one file. This is usually the case but there are exceptions, for example when license is written as two different license files (e.g. Perl_5 license is actually two alternative licenses: GPL and Artistic).
Policies have individual default filenames, see Software::Policies.
AUTHOR
Mikko Koivunalho <mikkoi@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2025 by Mikko Koivunalho.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.