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 that 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### Where to send patches and pull requests
55
56If you found this distribution on Github, sending a pull-request is the
57best way to contribute.
58
59If a pull-request isn't possible, a bug ticket with a patch file is the
60next best option.
61
62As a last resort, an email to the author(s) is acceptable.
63
64## Installing and using Dist::Zilla
65
66Dist::Zilla is not required for contributing, but if you'd like to learn
67more, this section will get you up to speed.
68
69Dist::Zilla is a very powerful authoring tool, optimized for maintaining a
70large number of distributions with a high degree of automation, but it has a
71large dependency chain, a bit of a learning curve and requires a number of
72author-specific plugins.
73
74To install it from CPAN, I recommend one of the following approaches for
75the quickest installation:
76
77    # using CPAN.pm, but bypassing non-functional pod tests
78    $ cpan TAP::Harness::Restricted
79    $ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla
80
81    # using cpanm, bypassing *all* tests
82    $ cpanm -n Dist::Zilla
83
84In either case, it's probably going to take about 10 minutes.  Go for a walk,
85go get a cup of your favorite beverage, take a bathroom break, or whatever.
86When you get back, Dist::Zilla should be ready for you.
87
88Then you need to install any plugins specific to this distribution:
89
90    $ cpan `dzil authordeps`
91    $ dzil authordeps | cpanm
92
93Once installed, here are some dzil commands you might try:
94
95    $ dzil build
96    $ dzil test
97    $ dzil xtest
98
99You can learn more about Dist::Zilla at http://dzil.org/
100
101