Blame CONTRIBUTING.mkdn

Packit f40462
## HOW TO CONTRIBUTE
Packit f40462
Packit f40462
Thank you for considering contributing to this distribution.  This file
Packit f40462
contains instructions that will help you work with the source code.
Packit f40462
Packit f40462
The distribution is managed with Dist::Zilla.  This means than many of the
Packit f40462
usual files you might expect are not in the repository, but are generated at
Packit f40462
release time, as is much of the documentation.  Some generated files are
Packit f40462
kept in the repository as a convenience (e.g. Makefile.PL or cpanfile).
Packit f40462
Packit f40462
Generally, **you do not need Dist::Zilla to contribute patches**.  You do need
Packit f40462
Dist::Zilla to create a tarball.  See below for guidance.
Packit f40462
Packit f40462
### Getting dependencies
Packit f40462
Packit f40462
If you have App::cpanminus 1.6 or later installed, you can use `cpanm` to
Packit f40462
satisfy dependencies like this:
Packit f40462
Packit f40462
    $ cpanm --installdeps .
Packit f40462
Packit f40462
Otherwise, look for either a `Makefile.PL` or `cpanfile` file for
Packit f40462
a list of dependencies to satisfy.
Packit f40462
Packit f40462
### Running tests
Packit f40462
Packit f40462
You can run tests directly using the `prove` tool:
Packit f40462
Packit f40462
    $ prove -l
Packit f40462
    $ prove -lv t/some_test_file.t
Packit f40462
Packit f40462
For most of my distributions, `prove` is entirely sufficient for you to test any
Packit f40462
patches you have. I use `prove` for 99% of my testing during development.
Packit f40462
Packit f40462
### Code style and tidying
Packit f40462
Packit f40462
Please try to match any existing coding style.  If there is a `.perltidyrc`
Packit f40462
file, please install Perl::Tidy and use perltidy before submitting patches.
Packit f40462
Packit f40462
If there is a `tidyall.ini` file, you can also install Code::TidyAll and run
Packit f40462
`tidyall` on a file or `tidyall -a` to tidy all files.
Packit f40462
Packit f40462
### Patching documentation
Packit f40462
Packit f40462
Much of the documentation Pod is generated at release time.  Some is
Packit f40462
generated boilerplate; other documentation is built from pseudo-POD
Packit f40462
directives in the source like C<=method> or C<=func>.
Packit f40462
Packit f40462
If you would like to submit a documentation edit, please limit yourself to
Packit f40462
the documentation you see.
Packit f40462
Packit f40462
If you see typos or documentation issues in the generated docs, please
Packit f40462
email or open a bug ticket instead of patching.
Packit f40462
Packit f40462
### Installing and using Dist::Zilla
Packit f40462
Packit f40462
Dist::Zilla is a very powerful authoring tool, optimized for maintaining a
Packit f40462
large number of distributions with a high degree of automation, but it has a
Packit f40462
large dependency chain, a bit of a learning curve and requires a number of
Packit f40462
author-specific plugins.
Packit f40462
Packit f40462
To install it from CPAN, I recommend one of the following approaches for
Packit f40462
the quickest installation:
Packit f40462
Packit f40462
    # using CPAN.pm, but bypassing non-functional pod tests
Packit f40462
    $ cpan TAP::Harness::Restricted
Packit f40462
    $ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla
Packit f40462
Packit f40462
    # using cpanm, bypassing *all* tests
Packit f40462
    $ cpanm -n Dist::Zilla
Packit f40462
Packit f40462
In either case, it's probably going to take about 10 minutes.  Go for a walk,
Packit f40462
go get a cup of your favorite beverage, take a bathroom break, or whatever.
Packit f40462
When you get back, Dist::Zilla should be ready for you.
Packit f40462
Packit f40462
Then you need to install any plugins specific to this distribution:
Packit f40462
Packit f40462
    $ cpan `dzil authordeps`
Packit f40462
    $ dzil authordeps | cpanm
Packit f40462
Packit f40462
Once installed, here are some dzil commands you might try:
Packit f40462
Packit f40462
    $ dzil build
Packit f40462
    $ dzil test
Packit f40462
    $ dzil xtest
Packit f40462
Packit f40462
You can learn more about Dist::Zilla at http://dzil.org/
Packit f40462