CONTRIBUTING.mkdn

   1 ## HOW TO CONTRIBUTE
   2
   3 Thank you for considering contributing to this distribution.  This file
   4 contains instructions that will help you work with the source code.
   5
   6 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
   8 release time, as is much of the documentation.  Some generated files are
   9 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
  12 Dist::Zilla to create a tarball.  See below for guidance.
  13
  14 ### Getting dependencies
  15
  16 If you have App::cpanminus 1.6 or later installed, you can use `cpanm` to
  17 satisfy dependencies like this:
  18
  19     $ cpanm --installdeps .
  20
  21 Otherwise, look for either a `Makefile.PL` or `cpanfile` file for
  22 a list of dependencies to satisfy.
  23
  24 ### Running tests
  25
  26 You can run tests directly using the `prove` tool:
  27
  28     $ prove -l
  29     $ prove -lv t/some_test_file.t
  30
  31 For most of my distributions, `prove` is entirely sufficient for you to test any
  32 patches you have. I use `prove` for 99% of my testing during development.
  33
  34 ### Code style and tidying
  35
  36 Please try to match any existing coding style.  If there is a `.perltidyrc`
  37 file, please install Perl::Tidy and use perltidy before submitting patches.
  38
  39 If there is a `tidyall.ini` file, you can also install Code::TidyAll and run
  40 `tidyall` on a file or `tidyall -a` to tidy all files.
  41
  42 ### Patching documentation
  43
  44 Much of the documentation Pod is generated at release time.  Some is
  45 generated boilerplate; other documentation is built from pseudo-POD
  46 directives in the source like C<=method> or C<=func>.
  47
  48 If you would like to submit a documentation edit, please limit yourself to
  49 the documentation you see.
  50
  51 If you see typos or documentation issues in the generated docs, please
  52 email or open a bug ticket instead of patching.
  53
  54 ### Installing and using Dist::Zilla
  55
  56 Dist::Zilla is a very powerful authoring tool, optimized for maintaining a
  57 large number of distributions with a high degree of automation, but it has a
  58 large dependency chain, a bit of a learning curve and requires a number of
  59 author-specific plugins.
  60
  61 To install it from CPAN, I recommend one of the following approaches for
  62 the quickest installation:
  63
  64     # using CPAN.pm, but bypassing non-functional pod tests
  65     $ cpan TAP::Harness::Restricted
  66     $ PERL_MM_USE_DEFAULT=1 HARNESS_CLASS=TAP::Harness::Restricted cpan Dist::Zilla
  67
  68     # using cpanm, bypassing *all* tests
  69     $ cpanm -n Dist::Zilla
  70
  71 In either case, it's probably going to take about 10 minutes.  Go for a walk,
  72 go get a cup of your favorite beverage, take a bathroom break, or whatever.
  73 When you get back, Dist::Zilla should be ready for you.
  74
  75 Then you need to install any plugins specific to this distribution:
  76
  77     $ cpan `dzil authordeps`
  78     $ dzil authordeps | cpanm
  79
  80 Once installed, here are some dzil commands you might try:
  81
  82     $ dzil build
  83     $ dzil test
  84     $ dzil xtest
  85
  86 You can learn more about Dist::Zilla at http://dzil.org/
  87