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 (e.g. Makefile.PL).
9
10Generally, **you do not need Dist::Zilla to contribute patches**.  You do need
11Dist::Zilla to create a tarball and/or install from the repository.  See below
12for guidance.
13
14### Getting dependencies
15
16See the included `cpanfile` file for a list of dependencies.  If you have
17App::cpanminus 1.6 or later installed, you can use `cpanm` to satisfy
18dependencies like this:
19
20    $ cpanm --installdeps .
21
22Otherwise, you can install Module::CPANfile 1.0002 or later and then satisfy
23dependencies with the regular `cpan` client and `cpanfile-dump`:
24
25    $ cpan `cpanfile-dump`
26
27### Running tests
28
29You can run tests directly using the `prove` tool:
30
31    $ prove -l
32    $ prove -lv t/some_test_file.t
33
34For most of my distributions, `prove` is entirely sufficient for you to test any
35patches you have. I use `prove` for 99% of my testing during development.
36
37### Code style and tidying
38
39Please try to match any existing coding style.  If there is a `.perltidyrc`
40file, please install Perl::Tidy and use perltidy before submitting patches.
41
42If 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.
44
45### Patching documentation
46
47Much of the documentation Pod is generated at release time.  Depending on the
48distribution, some of my documentation may be written in a Pod dialect called
49WikiDoc. (See Pod::WikiDoc on CPAN.)
50
51If you would like to submit a documentation edit, please limit yourself to the
52documentation you see.
53
54If you see typos or documentation issues in the generated docs, please
55email or open a bug ticket instead of patching.
56
57### Installing from the repository
58
59If you want to install directly from the repository, you need to have
60Dist::Zilla installed (see below).  If this is a burden to you, I welcome
61patches against a CPAN tarball instead of the repository.
62
63### Installing and using Dist::Zilla
64
65Dist::Zilla is a very powerful authoring tool, optimized for maintaining a
66large number of distributions with a high degree of automation, but it has a
67large dependency chain, a bit of a learning curve and requires a number of
68author-specific plugins.
69
70To install it from CPAN, I recommend one of the following approaches for
71the quickest installation:
72
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
76
77    # using cpanm, bypassing *all* tests
78    $ cpanm -n Dist::Zilla
79
80In either case, it's probably going to take about 10 minutes.  Go for a walk,
81go get a cup of your favorite beverage, take a bathroom break, or whatever.
82When you get back, Dist::Zilla should be ready for you.
83
84Then you need to install any plugins specific to this distribution:
85
86    $ cpan `dzil authordeps`
87    $ dzil authordeps | cpanm
88
89Once installed, here are some dzil commands you might try:
90
91    $ dzil build
92    $ dzil test
93    $ dzil xtest
94
95To install from the repository, use:
96
97    $ dzil install
98
99You can learn more about Dist::Zilla at http://dzil.org/
100
101