NAME

Dist::Template - CORIONs distribution template

DESCRIPTION

This directory is a template for a fresh or existing distribution of Perl code ready-made for CPAN.

The main idea is that Makefile.PL is the main source of truth for the distribution. From this source of truth, the following information gets derived:

META.json, META.yml

The approach follows the idea that you have one "main" file in your distribution. From that main file the following information is extracted:

Distribution version number
README.* contents

USAGE

The Makefile.PL is dual-purpose. One use is to maintain documentation extracts for Github and CPAN during development. The second use is to install the module at installation time.

SETUP STEPS

Initialize git (or whatever) version control in your distribution directory
Copy the contents of the template/ directory into your new (or existing) distribution
```
cp -rp ../Dist-Template/template/. .
```
Edit Makefile.PL to list all prerequisites.
Edit MANIFEST.SKIP to exclude stuff you don't want.
Generate README.md for Github.
```
perl Makefile.PL
```
This will blindly overwrite your existing README.md. This is why you committed everything to version control before.
Check that the author tests pass, or make them pass:
```
perl Makefile.PL
make
prove -bl xt/
```
Add all files to version control

RELEASE STEPS

Bump the version
```
perl-reversion -bump
```

Update the meta-files

perl ../Dist-Template/tools/update-meta.pl

Add release date to Changes. The release date must be formatted like this:
```
YYYY-MM-DD 0.01
```
(Re)run the author tests
```
perl Makefile.PL
make
prove -bl xt/
```
Commit everything
Release using Module::Release and CPAN::Uploader

FILES AND THEIR USE

The distribution is based on ExtUtils::MakeMaker, so most of the files are relevant for ExtUtils::MakeMaker.

.appveyor.yml

A rough template to test a plain Perl distribution on Appveyor. The distribution still needs to be enabled for testing on Appveyor.

.gitignore

As I use git for version control, this file is a template of files that do not need to go under version control. I'm a firm believer in the approach that everything should be under version control, even files that are completely derived from other files. This is why META.* is not excluded here.

.travis.yml

A rough template to test a plain Perl distribution on Travis CI. The distribution still needs to be enabled for testing on Travis CI.

Changes

List of changes between versions.

LICENSE

A copy of the Artistic License 2, because I release most of my code under it.

Makefile.PL

The heart of maintaining a distribution.

MANIFEST.SKIP

List of regexps excluding items from the distribution on CPAN.

README.*

Various incarnations of information extracted from the main file of the distribution.

t/

The module test suite lives in here.

tools/

A directory keeping maintenance tools. You can always delete this.

xt/

Author tests. Run these with

perl Makefile.PL
make
prove -bl xt/