Blame CONTRIBUTING.mkdn

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