Blame CONTRIBUTING.mkdn

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