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