CONTRIBUTING.mkdn 2.98 KB
Newer Older
1
## HOW TO CONTRIBUTE
David Golden's avatar
David Golden committed
2 3 4 5 6

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
7
usual files you might expect are not in the repository, but are generated at
David Golden's avatar
David Golden committed
8 9
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).
10 11

Generally, **you do not need Dist::Zilla to contribute patches**.  You do need
David Golden's avatar
David Golden committed
12
Dist::Zilla to create a tarball.  See below for guidance.
David Golden's avatar
David Golden committed
13

14
### Getting dependencies
David Golden's avatar
David Golden committed
15

David Golden's avatar
David Golden committed
16 17
If you have App::cpanminus 1.6 or later installed, you can use `cpanm` to
satisfy dependencies like this:
David Golden's avatar
David Golden committed
18

19 20
    $ cpanm --installdeps .

David Golden's avatar
David Golden committed
21 22
Otherwise, look for either a `Makefile.PL` or `cpanfile` file for
a list of dependencies to satisfy.
23 24 25 26 27 28 29 30

### Running tests

You can run tests directly using the `prove` tool:

    $ prove -l
    $ prove -lv t/some_test_file.t

31 32
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.
David Golden's avatar
David Golden committed
33

David Golden's avatar
David Golden committed
34 35
### Code style and tidying

David Golden's avatar
David Golden committed
36 37 38 39 40
Please try to match any existing coding style.  If there is a `.perltidyrc`
file, please install Perl::Tidy and use perltidy before submitting patches.

If there is a `tidyall.ini` file, you can also install Code::TidyAll and run
`tidyall` on a file or `tidyall -a` to tidy all files.
David Golden's avatar
David Golden committed
41

42 43
### Patching documentation

David Golden's avatar
David Golden committed
44 45 46
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>.
47

David Golden's avatar
David Golden committed
48 49
If you would like to submit a documentation edit, please limit yourself to
the documentation you see.
David Golden's avatar
David Golden committed
50 51 52 53

If you see typos or documentation issues in the generated docs, please
email or open a bug ticket instead of patching.

54
### Installing and using Dist::Zilla
55

56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
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:
David Golden's avatar
David Golden committed
76

77 78
    $ cpan `dzil authordeps`
    $ dzil authordeps | cpanm
David Golden's avatar
David Golden committed
79 80 81

Once installed, here are some dzil commands you might try:

82 83 84 85
    $ dzil build
    $ dzil test
    $ dzil xtest

David Golden's avatar
David Golden committed
86 87
You can learn more about Dist::Zilla at http://dzil.org/