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