3
Thank you for considering contributing to this distribution. This file
4
contains instructions that will help you work with the source code.
6
The distribution is managed with Dist::Zilla. This means than many of the
7
usual files you might expect are not in the repository, but are generated at
8
release time (e.g. Makefile.PL).
10
Generally, **you do not need Dist::Zilla to contribute patches**. You do need
11
Dist::Zilla to create a tarball and/or install from the repository. See below
14
### Getting dependencies
16
See the included `cpanfile` file for a list of dependencies. If you have
17
App::cpanminus 1.6 or later installed, you can use `cpanm` to satisfy
18
dependencies like this:
20
$ cpanm --installdeps .
22
Otherwise, you can install Module::CPANfile 1.0002 or later and then satisfy
23
dependencies with the regular `cpan` client and `cpanfile-dump`:
25
$ cpan `cpanfile-dump`
29
You can run tests directly using the `prove` tool:
32
$ prove -lv t/some_test_file.t
34
For most of my distributions, `prove` is entirely sufficient for you to test any
35
patches you have. I use `prove` for 99% of my testing during development.
37
### Code style and tidying
39
Please try to match any existing coding style. If there is a `.perltidyrc`
40
file, please install Perl::Tidy and use perltidy before submitting patches.
42
If there is a `tidyall.ini` file, you can also install Code::TidyAll and run
43
`tidyall` on a file or `tidyall -a` to tidy all files.
45
### Patching documentation
47
Much of the documentation Pod is generated at release time. Depending on the
48
distribution, some of my documentation may be written in a Pod dialect called
49
WikiDoc. (See Pod::WikiDoc on CPAN.)
51
If you would like to submit a documentation edit, please limit yourself to the
52
documentation you see.
54
If you see typos or documentation issues in the generated docs, please
55
email or open a bug ticket instead of patching.
57
### Installing from the repository
59
If you want to install directly from the repository, you need to have
60
Dist::Zilla installed (see below). If this is a burden to you, I welcome
61
patches against a CPAN tarball instead of the repository.
63
### Installing and using Dist::Zilla
65
Dist::Zilla is a very powerful authoring tool, optimized for maintaining a
66
large number of distributions with a high degree of automation, but it has a
67
large dependency chain, a bit of a learning curve and requires a number of
68
author-specific plugins.
70
To install it from CPAN, I recommend one of the following approaches for
71
the quickest installation:
73
# using CPAN.pm, but bypassing non-functional pod tests
74
$ cpan TAP::Harness::Restricted
75
$ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla
77
# using cpanm, bypassing *all* tests
78
$ cpanm -n Dist::Zilla
80
In either case, it's probably going to take about 10 minutes. Go for a walk,
81
go get a cup of your favorite beverage, take a bathroom break, or whatever.
82
When you get back, Dist::Zilla should be ready for you.
84
Then you need to install any plugins specific to this distribution:
86
$ cpan `dzil authordeps`
87
$ dzil authordeps | cpanm
89
Once installed, here are some dzil commands you might try:
95
To install from the repository, use:
99
You can learn more about Dist::Zilla at http://dzil.org/
added
removed
CONTRIBUTING
