Skip to content

Latest commit

 

History

History
206 lines (126 loc) · 6.28 KB

CONTRIBUTING.pod

File metadata and controls

206 lines (126 loc) · 6.28 KB
Raw

CONTENTS

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, you do not need Dist::Zilla to contribute patches. You may need Dist::Zilla to create a tarball. See below for guidance.

Getting dependencies

If you have App::cpanminus 1.6 or later installed, you can use cpanm to satisfy dependencies like this:

$ cpanm --installdeps .

Otherwise, look for either a Makefile.PL or cpanfile file for a list of dependencies to satisfy.

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.

Code style and tidying

Please try to match any existing coding style. If there is a .perltidyrc file, please install Perl::Tidy and use perltidy before submitting patches.

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 =method or =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.

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/

OTHER SHORTCUTS

I use a few other tricks that might prove useful to know about when hacking on my dists.

Install and Test using a pre-made build branch

Most of my repositories come with 1 or more pre-made build branches, which may occur under any of the following names:

  • builds - my last dzil build

  • releases - the build generated for the most recent CPAN release

  • build/master ( legacy version of builds )

These branches contain committed copies of my own local 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.

Locally Patch dist.ini

The majority of Dist::Zilla authors ship around a load of shared configuration in a personal @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: dist.ini is a flattened unbundled version of dist.ini.meta

As such, you can tell exactly which plugins are being consumed simply by looking at dist.ini. And you can tell 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 wanting to work with the full Dist::Zilla stack, you can freely just yank them out and keep on trucking without having to memorize the arcane syntax my bundle requires.

Doing Long-Term dist.ini patches

If you find yourself wanting to make and submit long term changes to dist.ini, then you may want to look into dist.ini.meta, and see the results of your changes in 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

CREDITS

This file was adapted from an initial CONTRIBUTING.mkdn file from David Golden under the terms of the Apache 2 license.