=encoding UTF-8 =head1 CONTENTS =over 4 =item * L</HOW TO CONTRIBUTE> =over 4 =item * L</Getting dependencies> =item * L</Running tests> =item * L</Code style and tidying> =item * L</Patching documentation> =item * L</Installing and using Dist::Zilla> =back =item * L</OTHER SHORTCUTS> =over 4 =item * L</Install and Test using a pre-made build branch> =item * L<< Locally Patch C<dist.ini> >> =over 4 =item * L<< /Doing Long-Term C<dist.ini> patches >> =back =back =item * L</CREDITS> =back =head1 HOW TO CONTRIBUTE Thank you for considering contributing to this distribution. This file contains instructions that will help you work with the source code. The distribution is managed with Dist::Zilla. This means than many of the usual files you might expect are not in the repository, but are generated at release time, as is much of the documentation. Some generated files are kept in the repository as a convenience (e.g. Makefile.PL or cpanfile). Generally, B<you do not need Dist::Zilla to contribute patches>. You may need Dist::Zilla to create a tarball. See below for guidance. =head2 Getting dependencies If you have App::cpanminus 1.6 or later installed, you can use C<cpanm> to satisfy dependencies like this: $ cpanm --installdeps . Otherwise, look for either a C<Makefile.PL> or C<cpanfile> file for a list of dependencies to satisfy. =head2 Running tests You can run tests directly using the `prove` tool: $ prove -l $ prove -lv t/some_test_file.t For most of my distributions, `prove` is entirely sufficient for you to test any patches you have. I use `prove` for 99% of my testing during development. =head2 Code style and tidying Please try to match any existing coding style. If there is a C<.perltidyrc> file, please install Perl::Tidy and use perltidy before submitting patches. =head2 Patching documentation Much of the documentation Pod is generated at release time. Some is generated boilerplate; other documentation is built from pseudo-POD directives in the source like C<=method> or C<=func>. If you would like to submit a documentation edit, please limit yourself to the documentation you see. If you see typos or documentation issues in the generated docs, please email or open a bug ticket instead of patching. =head2 Installing and using Dist::Zilla Dist::Zilla is a very powerful authoring tool, optimized for maintaining a large number of distributions with a high degree of automation, but it has a large dependency chain, a bit of a learning curve and requires a number of author-specific plugins. To install it from CPAN, I recommend one of the following approaches for the quickest installation: # using CPAN.pm, but bypassing non-functional pod tests $ cpan TAP::Harness::Restricted $ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla # using cpanm, bypassing *all* tests $ cpanm -n Dist::Zilla In either case, it's probably going to take about 10 minutes. Go for a walk, go get a cup of your favorite beverage, take a bathroom break, or whatever. When you get back, Dist::Zilla should be ready for you. Then you need to install any plugins specific to this distribution: $ cpan `dzil authordeps` $ dzil authordeps | cpanm Once installed, here are some dzil commands you might try: $ dzil build $ dzil test $ dzil xtest You can learn more about Dist::Zilla at http://dzil.org/ =head1 OTHER SHORTCUTS I use a few other tricks that might prove useful to know about when hacking on my dists. =head2 Install and Test using a pre-made build branch Most of my repositories come with 1 or more pre-made C<build> branches, which may occur under any of the following names: =over 4 =item * C<builds> - my last C<dzil build> =item * C<releases> - the build generated for the most recent CPAN release =item * C<build/master> ( I<legacy> version of C<builds> ) =back These branches contain committed copies of my own local C<dzil build> invocations. Checking out a copy of these branches with git checkout builds Will get you a full working built tree, which will look identical to how the distribution will look once I ship it. Having this is not entirely necessary as you should be able to do similar simply working on the master branch ( with a few caveats around POD handling ) But its there if you need it. Additionally: These branches are part of my Travis testing infrastructure which help ascertain that the module will work and pass tests without the benefit of having 3-halves of CPAN due to developer dependencies. =head2 Locally Patch C<dist.ini> The majority of C<Dist::Zilla> authors ship around a load of shared configuration in a personal C<@Bundle>, which makes replicating configuration to their different distributions simpler. This has a downside that every time they make a minor tweak to their bundle, everywhere that was currently using that bundle gets the changes, and not all those changes will necessarily work with their code. The bundle system also makes it tricky for people to simply patch-out single plugins that are causing local problems for them because they're hidden behind the bundle façade. Here, I use a system from generating a frozen snapshot of the state of my bundle: C<dist.ini> is a flattened unbundled version of C<dist.ini.meta> As such, you can tell B<exactly> which plugins are being consumed simply by looking at C<dist.ini>. And you can tell B<exactly> what their configuration is and their intended order is. So if you're hacking on one of my dists and a plugin or two get in your way and you're I<wanting> to work with the full C<Dist::Zilla> stack, you can freely just yank them out and keep on trucking without having to memorize the arcane syntax my bundle requires. =head3 Doing Long-Term C<dist.ini> patches If you find yourself wanting to make and submit long term changes to dist.ini, B<then> you I<may> want to look into C<dist.ini.meta>, and see the results of your changes in C<dist.ini> after making changes by performing: dzil bakeini This will possibly require installing the following, which are not strictly required for building my dists: Dist::Zilla::PluginBundle::Author::KENTNL Dist::Zilla::App::Command::bakeini =head1 CREDITS This file was adapted from an initial C<CONTRIBUTING.mkdn> file from David Golden under the terms of the Apache 2 license.