1## HOW TO CONTRIBUTE
2
3Thank you for considering contributing to this distribution.  This file
4contains instructions that will help you work with the source code.
5
6The distribution is managed with Dist::Zilla.  This means than many of the
7usual files you might expect are not in the repository, but are generated at
8release time, as is much of the documentation.  Some generated files are
9kept in the repository as a convenience (e.g. Makefile.PL or cpanfile).
10
11Generally, **you do not need Dist::Zilla to contribute patches**.  You do need
12Dist::Zilla to create a tarball.  See below for guidance.
13
14### Getting dependencies
15
16If you have App::cpanminus 1.6 or later installed, you can use `cpanm` to
17satisfy dependencies like this:
18
19    $ cpanm --installdeps .
20
21Otherwise, look for either a `Makefile.PL` or `cpanfile` file for
22a list of dependencies to satisfy.
23
24### Running tests
25
26You can run tests directly using the `prove` tool:
27
28    $ prove -l
29    $ prove -lv t/some_test_file.t
30
31For most of my distributions, `prove` is entirely sufficient for you to test any
32patches you have. I use `prove` for 99% of my testing during development.
33
34### Code style and tidying
35
36Please try to match any existing coding style.  If there is a `.perltidyrc`
37file, please install Perl::Tidy and use perltidy before submitting patches.
38
39If there is a `tidyall.ini` file, you can also install Code::TidyAll and run
40`tidyall` on a file or `tidyall -a` to tidy all files.
41
42### Patching documentation
43
44Much of the documentation Pod is generated at release time.  Some is
45generated boilerplate; other documentation is built from pseudo-POD
46directives in the source like C<=method> or C<=func>.
47
48If you would like to submit a documentation edit, please limit yourself to
49the documentation you see.
50
51If you see typos or documentation issues in the generated docs, please
52email or open a bug ticket instead of patching.
53
54### Installing and using Dist::Zilla
55
56Dist::Zilla is a very powerful authoring tool, optimized for maintaining a
57large number of distributions with a high degree of automation, but it has a
58large dependency chain, a bit of a learning curve and requires a number of
59author-specific plugins.
60
61To install it from CPAN, I recommend one of the following approaches for
62the quickest installation:
63
64    # using CPAN.pm, but bypassing non-functional pod tests
65    $ cpan TAP::Harness::Restricted
66    $ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla
67
68    # using cpanm, bypassing *all* tests
69    $ cpanm -n Dist::Zilla
70
71In either case, it's probably going to take about 10 minutes.  Go for a walk,
72go get a cup of your favorite beverage, take a bathroom break, or whatever.
73When you get back, Dist::Zilla should be ready for you.
74
75Then you need to install any plugins specific to this distribution:
76
77    $ cpan `dzil authordeps`
78    $ dzil authordeps | cpanm
79
80Once installed, here are some dzil commands you might try:
81
82    $ dzil build
83    $ dzil test
84    $ dzil xtest
85
86You can learn more about Dist::Zilla at http://dzil.org/
87
88